From 13ad490b4f0cef6e803153170ecb37d44d1f05ae Mon Sep 17 00:00:00 2001 From: Juan RP Date: Thu, 5 Feb 2009 16:12:00 +0100 Subject: [PATCH] More documentation bits... I hate this part. --HG-- extra : convert_revision : 63d8524fd28a480c88731b717d55d1f822adf9cc --- doc/BINPKG_INFO | 34 +++++++++++++ doc/BINPKG_REPOSITORY | 8 +++ doc/README | 111 ++++------------------------------------ doc/SRCPKG_INFO | 114 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 165 insertions(+), 102 deletions(-) create mode 100644 doc/SRCPKG_INFO diff --git a/doc/BINPKG_INFO b/doc/BINPKG_INFO index a5eba17902..feda063540 100644 --- a/doc/BINPKG_INFO +++ b/doc/BINPKG_INFO @@ -1,3 +1,7 @@ +------------------------------------------------------------------------------ + BRIEF INTRODUCTION +------------------------------------------------------------------------------ + A binary package built with xbps is a normal tar(1) archive, compressed with bzip2 and has the following structure: @@ -63,3 +67,33 @@ at pre/post installation/removal of the binary package. The package's dictionary will also be written into the repository's package index file, that describes information about a binary package on it. See the BINPKG_REPOSITORY file for more info about repositories. + +------------------------------------------------------------------------------ + HOW TO USE BINARY PACKAGES +------------------------------------------------------------------------------ + +To install binary packages, firstly a repository must be created as well as +some binary packages for it. The flow for this task is: + + 1- xbps-src install + 2- xbps-src build-pkg all + 3- xbps-src genindex + 4- xbps-repo add $XBPS_PACKAGES + 5- xbps-bin install -r /rootdir + +So the tasks are: install the package into destdir (and all its dependencies), +build the binary package from the required package, generate the repository +index, add the repository into the pool and install the binary package. + +Please note that by default, the xbps-* utils accept the -r flag, to specify +the root directory for all operations, in that case the package will be +installed into and metadata files into /var/cache/xbps. + +Don't forget to set this flag if you aren't using xbps as the primary +package manager in your system, otherwise it could overwrite some files! + +See the BINPKG_REPOSITORY file for more info about repositories for +binary packages or SRCPKG_INFO for source packages. + +------------------------------------------------------------------------------ + Juan Romero Pardines diff --git a/doc/BINPKG_REPOSITORY b/doc/BINPKG_REPOSITORY index 173bb66785..2049295fa3 100644 --- a/doc/BINPKG_REPOSITORY +++ b/doc/BINPKG_REPOSITORY @@ -1,3 +1,7 @@ +------------------------------------------------------------------------------ + BRIEF INTRODUCTION +------------------------------------------------------------------------------ + A repository for binary packages contains the packages itself, and an index file describing the information about available packages. @@ -65,6 +69,10 @@ Here's how the package index plist file shall look like in a repository: +------------------------------------------------------------------------------ + HOW TO USE BINPKGS WITH REPOSITORIES +------------------------------------------------------------------------------ + To build binary packages from all currently installed packages in XBPS_MASTERDIR: diff --git a/doc/README b/doc/README index a46d87f5a0..c2acad0daa 100644 --- a/doc/README +++ b/doc/README @@ -29,7 +29,8 @@ http://code.google.com/p/portableproplib/ I'm also the human maintaining the portable proplib package. I'd suggest you to install it into /usr/local to avoid issues with your distribution packages. -Additionally the following software is required to be able to use xbps: +Additionally the following software is required to be able to build and install +xbps binary/source packages: * GNU Binutils * GNU Bison @@ -55,110 +56,16 @@ PLEASE NOTE THAT fakechroot or fakeroot-ng DO NOT WORK. Before using xbps, some required utilities need to be built and installed into $(PREFIX); by default they are installed into /usr/local. You can do this by issuing "make" and "make install" as root in the top -level directory. +level directory. See the REQUIREMENTS section above for required packages. -Now you should edit the configuration file located in the etc directory -in the top level directory. By default it uses the xbps directory in -your $HOME. +Once the xbps distfiles are installed into prefix, you can start building +packages from source, add local repositories with binary packages, install or +remove them, etc. -If configuration file is not specified from the command line with the --c flag, it will first try to use the default location at -/usr/local/etc/xbps.conf, and as last resort in the etc directory of the -current directory. +If you are only interested in building/using packages from source, see the +SRCPKG_INFO file. -To avoid problems with libtool and configure scripts finding stuff that is -available in the host system, almost all packages must be built inside of a -chroot. So the first thing would be to create the binary packages with: - - $ xbps-src install xbps-base-chroot - -This will build all required packages via fakeroot in masterdir, therefore you -can run it as normal user. Next commands will require super-user privileges -and all package handling will be done within the chroot. I believe it's the -most easier and faster way to handle clean dependencies; another reason would -be that xbps packages are meant to be used in a system and not just for -ordinary users. So once all packages are built, you can create and enter -to the chroot with: - - $ sudo xbps-src chroot - -Press Control + D to exit from the chroot. The following targets will require -to be done in the chroot: - - build, configure, install, install-destdir, remove, stow and unstow. - -Now let's explain some more about the targets that you can use. To start -installing packages you should use the install target: - - $ sudo xbps-src install glib - -If the package is properly installed, it will be "stowned" automatically. -``stowned´´ means that this package is available in the master directory, -on which xpbs has copied all files from DESTDIR/. - -To remove a currently installed (and stowned) package, you can use: - - $ sudo xbps-src remove glib - -Please note that when you remove it, the package will also be removed -from XBPS_DESTDIR and previously "unstowned". - -To stow an already installed package (from XBPS_DESTDIR/): - - $ sudo xbps-src stow glib - -and to unstow an already installed (stowned) package: - - $ sudo xbps-src unstow glib - -You can also print some stuff about any template build file, e.g: - - $ xbps-src info glib - -To list installed (stowned) packages, use this: - - $ xbps-src list - -To only extract the distfiles, without configuring/building/installing: - - $ xbps-src extract foo - -To not remove the build directory after successful installation: - - $ sudo xbps-src -C install blah - -To only fetch the distfile: - - $ xbps-src fetch blah - -To only install the package, _without_ stowning it into the master directory: - - $ sudo xbps-src install-destdir blob - -To list files installed by a package, note that package must be installed -into destination directory first: - - $ xbps-src listfiles blob - ------------------------------------------------------------------------------- - PERFORMANCE ------------------------------------------------------------------------------- - -xbps is really fast, trust me. That was one of my reasons to make my own -pkgsrc/ports alike system. - -If you want benchmarks, here is one: building libX11 and all its dependencies -required (not included building xstow) with xbps: - - 251.20s real 121.36s user 53.94s system - -versus pkgsrc (make install clean clean-depends and digest previously -installed): - - 450.41s real 167.58s user 97.31s system - -That's more or less 40% faster! that's the price you pay for having those -wrappers in pkgsrc that aren't very useful on NetBSD :-) +For information about binary packages, see the BINPKG_INFO file. ------------------------------------------------------------------------------ Juan Romero Pardines diff --git a/doc/SRCPKG_INFO b/doc/SRCPKG_INFO new file mode 100644 index 0000000000..94e218d631 --- /dev/null +++ b/doc/SRCPKG_INFO @@ -0,0 +1,114 @@ +----------------------------------------------------------------------------- + REQUIREMENTS +----------------------------------------------------------------------------- + +To be able to build packages the following software is required: + + * GNU Binutils + * GNU Bison + * GNU GCC C++ (plus GMP and MPFR) development packages. + * GNU Gettext + * GNU Make + * GNU m4 + * fakeroot + * ncurses (development package). + * wget + * libarchive (development package). + +Super-user privileges are required as well, because all packages are built +in a chroot (except the ones that are included in a virtual package to be +able to build a minimal system for the chroot). + +PLEASE NOTE THAT fakechroot or fakeroot-ng DO NOT WORK. + +------------------------------------------------------------------------------ + HOW TO BUILD/HANDLE PACKAGES FROM SOURCE +------------------------------------------------------------------------------ + +Before using xbps-src, some required utilities need to be built and installed +into $(PREFIX); by default they are installed into /usr/local. +You can do this by issuing "make" and "make install" as root in the top +level directory. + +If configuration file is not specified from the command line with the +-c flag, it will first try to use the default location at +/usr/local/etc/xbps.conf (or the installation prefix that was specified +to the make(1) command), and as last resort in the etc directory of the +current directory. + +To avoid problems with libtool and configure scripts finding stuff that is +available in the host system, almost all packages must be built inside of a +chroot. So the first thing would be to create the binary packages with: + + $ xbps-src install xbps-base-chroot + +This will build all required packages via fakeroot in masterdir, therefore you +can run it as normal user. Next commands will require super-user privileges +and all package handling will be done within the chroot. I believe it's the +most easier and faster way to handle clean dependencies; another reason would +be that xbps packages are meant to be used in a system and not just for +ordinary users. So once all packages are built, you can create and enter +to the chroot with: + + $ sudo xbps-src chroot + +Press Control + D to exit from the chroot. The following targets will require +to be done in the chroot: + + build, configure, install, install-destdir, remove, stow and unstow. + +Now let's explain some more about the targets that you can use. To start +installing packages you should use the install target: + + $ sudo xbps-src install glib + +If the package is properly installed, it will be "stowned" automatically. +``stowned´´ means that this package is available in the master directory, +on which xpbs has copied all files from DESTDIR/. + +To remove a currently installed (and stowned) package, you can use: + + $ sudo xbps-src remove glib + +Please note that when you remove it, the package will also be removed +from XBPS_DESTDIR and previously "unstowned". + +To stow an already installed package (from XBPS_DESTDIR/): + + $ sudo xbps-src stow glib + +and to unstow an already installed (stowned) package: + + $ sudo xbps-src unstow glib + +You can also print some stuff about any template build file, e.g: + + $ xbps-src info glib + +To list installed (stowned) packages, use this: + + $ xbps-src list + +To only extract the distfiles, without configuring/building/installing: + + $ xbps-src extract foo + +To not remove the build directory after successful installation: + + $ sudo xbps-src -C install blah + +To only fetch the distfile: + + $ xbps-src fetch blah + +To only install the package, _without_ stowning it into the master directory: + + $ sudo xbps-src install-destdir blob + +To list files installed by a package, note that package must be installed +into destination directory first: + + $ xbps-src listfiles blob + +------------------------------------------------------------------------------ + Juan Romero Pardines