diff --git a/README b/building-from-source.txt similarity index 62% rename from README rename to building-from-source.txt index f9f7b553242..329a46ce3d4 100644 --- a/README +++ b/building-from-source.txt @@ -1,25 +1,66 @@ xbps-src - building packages from source ======================================== -What is it? ------------ +Introduction +------------ `xbps-src` is the utility used by the _X binary package system_ to build -binary packages from source distribution files. A root directory `srcpkgs` +binary packages from source distribution files. A root directory (`srcpkgs`) contains multiple subdirs, each one to build a package as its name -indicates. The following example illustrates it: +indicates. The following directory structure illustrates it: + + ................................. -xbps-templates/ - | - |----- srcpkgs/ - | - |----- binutils/ - |----- gcc/ - |----- glibc/ - |----- .... + xbps-templates/ + | + |-----srcpkgs/ + | + |-----binutils/ + |-----gcc/ + |-----glibc/ .................................. +A package subdirectory always has a `template` file, that are the +specifications to download and build the binary package from its source files. +Additionally some packages may have additional subdirs on it: `files` +and `patches`. The `files` subdir may contain configuration files, or +any other file required to build the package. The `patches` subdir contains +patches that are applied to the source before building. + + + + + +Some packages may provide `subpackages`; they are different binary packages +that are built from the same source package. Each `subpackage` in the directory +structure (as shown above) is a symlink to the `real` package subdir, like this: + + + + +.................................... + srcpkgs/ + | + |-----gcc/ + |-----libgomp -> gcc + |-----libmudflap -> gcc + |-----libstdc++ -> gcc +.................................... + +Each subpackage uses its own `template` build file that is contained in +the `real` package subdir, and they have exactly the same name than the +symlink pointing to the `real` package subdir. The following example +illustrates the structure used by the _udev_ package in the filesystem: + + + + +....................................... + srcpkgs/ + | + |-----libgudev-devel -> udev + |-----libgudev -> udev + |-----udev-devel -> udev + |-----udev/ + |----template + |----libgudev-devel.template + |----libgudev.template + |----udev-devel.template +....................................... + Requirements ------------ The following software is required in the host system to build XBPS @@ -37,11 +78,21 @@ binary packages from source: - perl - sudo +Starting up +----------- +Firstly you'll have to download the `git` repository that contains `xbps-src` +and the build template files. To clone it with `git` use: + +---------------------------------------------------- +$ git clone git://repo.or.cz/xbps.git xbps-templates +---------------------------------------------------- + `xbps-src` and its shell utilities need to be installed in a directory for correct operation, that is accomplished by issuing: ------------------------------------ -$ cd xbps-src && make install clean ------------------------------------ + +-------------------------------------------------- +$ cd xbps-templates/xbps-src && make install clean +-------------------------------------------------- This will install all files into `/usr/local` by default, can be changed by specifying `PREFIX` and `DESTDIR` to make(1). @@ -54,21 +105,24 @@ are located in the `srcpkgs` directory, you should change the cwd to the directory matching the package that you want to work on, i.e for binutils, its directory is `srcpkgs/binutils`. + + + If configuration file is not specified from the command line with the --c flag, it will first try to use the default location at +`-c` flag, it will first try to use the default location at `/usr/local/etc/xbps-src.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 required set of packages that will be used in the chroot: -------------------------------------------------- -$ cd srcpkgs/xbps-base-chroot && xbps-src install -------------------------------------------------- + +---------------------------------------------------------------- +$ cd xbps-templates/srcpkgs/xbps-base-chroot && xbps-src install +---------------------------------------------------------------- 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 @@ -86,41 +140,49 @@ Press Control + D to exit from the chroot. The following targets will require to be done in the chroot (_once xbps-base-chroot is installed_): *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, all source packages are located in the `srcpkgs` directory, so to install glib: + ------------------------------------------ -$ cd srcpkgs/glib && sudo xbps-src install +~/srcpkgs/glib$ sudo xbps-src install ------------------------------------------ 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: + ----------------------------------------- -$ cd srcpkgs/glib && sudo xbps-src remove +~/srcpkgs/glib$ sudo xbps-src remove ----------------------------------------- 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/): + --------------------------------------- -$ cd srcpkgs/glib && sudo xbps-src stow +~/srcpkgs/glib$ sudo xbps-src stow --------------------------------------- To unstow an already installed (stowned) package: + ----------------------------------------- -$ cd srcpkgs/glib && sudo xbps-src unstow +~/srcpkgs/glib$ sudo xbps-src unstow ----------------------------------------- You can also print some stuff about any template build file, e.g: + ---------------------------------- -$ cd srcpkgs/glib && xbps-src info +~/srcpkgs/glib$ xbps-src info ---------------------------------- To list installed (stowned) packages, use this: @@ -129,23 +191,25 @@ $ xbps-src list --------------- To only extract the distfiles, without configuring/building/installing: + ------------------------------------ -$ cd srcpkgs/foo && xbps-src extract +~/srcpkgs/glib$ xbps-src extract ------------------------------------ To not remove the build directory after successful installation: + --------------------------------------------- -$ cd srcpkgs/blah && sudo xbps-src -C install +~/srcpkgs/glib$ sudo xbps-src -C install --------------------------------------------- To only fetch the distfile: ----------------------------------- -$ cd srcpkgs/blah && xbps-src fetch +~/srcpkgs/glib$ xbps-src fetch ----------------------------------- To only install the package, _without_ stowning it into the master directory: -------------------------------------------------- -$ cd srcpkgs/blob && sudo xbps-src install-destdir +~/srcpkgs/glib$ sudo xbps-src install-destdir -------------------------------------------------- To list files installed by a package, note that package must be installed