README

   1 xbps-src - building packages from source
   2 ========================================
   3
   4 Introduction
   5 ------------
   6 `xbps-src` is the utility used by the _X binary package system_ to build
   7 binary packages from source distribution files. A root directory (`srcpkgs`)
   8 contains multiple subdirs, each one to build a package as its name
   9 indicates. The following directory structure illustrates it:
  10  +
  11 .................................
  12   xbps-templates/
  13       |
  14       |-----srcpkgs/
  15                |
  16                |-----binutils/
  17                |-----gcc/
  18                |-----glibc/
  19 ..................................
  20
  21 A package subdirectory always has a `template` file, that are the
  22 specifications to download and build the binary package from its source files.
  23 Additionally some packages may have additional subdirs on it: `files`
  24 and `patches`. The `files` subdir may contain configuration files, or
  25 any other file required to build the package. The `patches` subdir contains
  26 patches that are applied to the source before building.
  27  +
  28
  29 Some packages may provide `subpackages`; they are different binary packages
  30 that are built from the same source package. Each `subpackage` in the directory
  31 structure (as shown above) is a symlink to the `real` package subdir, like this:
  32  +
  33 ....................................
  34   srcpkgs/
  35      |
  36      |-----gcc/
  37      |-----libgomp -> gcc
  38      |-----libmudflap -> gcc
  39      |-----libstdc++ -> gcc
  40 ....................................
  41
  42 Each subpackage uses its own `template` build file that is contained in
  43 the `real` package subdir, and they have exactly the same name than the
  44 symlink pointing to the `real` package subdir. The following example
  45 illustrates the structure used by the _udev_ package in the filesystem:
  46  +
  47 .......................................
  48   srcpkgs/
  49     |
  50     |-----libgudev-devel -> udev
  51     |-----libgudev -> udev
  52     |-----libudev-devel -> udev
  53     |-----libudev -> udev
  54     |-----udev/
  55            |----template
  56            |----libgudev-devel.template
  57            |----libgudev.template
  58            |----libudev-devel.template
  59            |----libudev.template
  60 .......................................
  61  +
  62
  63 Subpackages use a reduced version of the main `template` build file, because
  64 the build and main install process is all done in the real `template` file.
  65 Usually those `<subpkg>.template` files only move files and directories
  66 to the `subpackage` destination directory, so they are always smaller.
  67
  68 Requirements
  69 ------------
  70 The following software is required in the host system to install xbps-src
  71 and its helpers:
  72
  73  - GCC, make, sed and libcap (depelopment package and setcap(8) command).
  74
  75 To build binary packages with xbps-src also the following software needs
  76 to be installed into the host system:
  77
  78  - awk, bash, bison, gcc c++, gettext, path, texinfo, perl and fakeroot.
  79  - xbps static utilities, available from http://launchpad.net/xbps.
  80
  81 Additionally if you want to work as 'root':
  82
  83  - sudo
  84
  85 Starting up
  86 -----------
  87 Firstly you'll have to download the `git` repository that contains `xbps-src`
  88 and the build template files. To clone it with `git` use:
  89
  90 ----------------------------------------------------
  91 $ git clone git://repo.or.cz/xbps.git xbps-templates
  92 ----------------------------------------------------
  93
  94 `xbps-src` and its shell utilities need to be installed in a directory
  95 for correct operation, that is accomplished by issuing:
  96
  97 --------------------------------------------------
  98 $ cd xbps-templates/xbps-src && make install clean
  99 --------------------------------------------------
 100
 101 This will install all files into `/usr/local` by default, can be changed
 102 by specifying `PREFIX` and `DESTDIR` to make(1).
 103
 104 Building packages from source
 105 -----------------------------
 106 `xbps-src` always look for a `template` file in current directory, that's what
 107 it specifies the package build definitions and such. The build templates
 108 are located in the `srcpkgs` directory, you should change the cwd to the
 109 directory matching the package that you want to work on, i.e for binutils,
 110 its directory is `srcpkgs/binutils`.
 111  +
 112  +
 113
 114 If configuration file is not specified from the command line with the
 115 `-c` flag, it will first try to use the default location at
 116 `/usr/local/etc/xbps-src.conf` (or the installation prefix that was specified
 117 to the make(1) command), and as last resort in the etc directory of the
 118 current directory.
 119  +
 120  +
 121
 122 To avoid problems with libtool and configure scripts finding stuff that is
 123 available in the host system, almost all packages must be built inside of a
 124 chroot. So the first thing would be to create the required set of packages
 125 that will be used in the chroot:
 126
 127 ----------------------------------------------------------------
 128 $ cd xbps-templates/srcpkgs/xbps-base-chroot && xbps-src install
 129 ----------------------------------------------------------------
 130
 131 This will build all required packages via fakeroot in masterdir, therefore you
 132 can run it as normal user. Once 'xbps-src-chroot' has been built and installed
 133 into the 'masterdir' all packages will be built inside of the chroot.
 134  +
 135  +
 136
 137 'xbps-src' supports building packages in the chroot with your normal user,
 138 thanks to the *POSIX.1e Capabilities* support in the Linux kernel. To use this
 139 the target filesystem must support *extended attributes*; right now they
 140 are supported on almost all Linux filesytems, such as *ext2*, *ext3*, *ext4*,
 141 *xfs*, and others. To enable this feature you have to uncomment the option
 142 'XBPS_USE_CAPABILITIES' from *xbps-src.conf*. *PLEASE NOTE* that it's
 143 commented out (disabled) by default.
 144  +
 145  +
 146
 147 I believe it's the most easier and faster way to handle clean dependencies;
 148 another reason would be that xbps packages are meant to be used in a system and
 149 not just for ordinary users. So once all packages are built, you can create and
 150 enter to the chroot with:
 151
 152 ----------------------
 153 $ xbps-src chroot
 154 ----------------------
 155
 156 Press Control + D to exit from the chroot. The following targets will require
 157 to be done in the chroot (_once xbps-base-chroot is installed_):
 158 *build, configure, install and install-destdir*.
 159  +
 160  +
 161
 162 Now let's explain some more about the targets that you can use. To start
 163 installing packages you should use the install target, all source packages
 164 are located in the `srcpkgs` directory, so to install glib:
 165
 166 ------------------------------------------
 167 $ cd srcpkgs/<pkgname> && xbps-src install
 168 ------------------------------------------
 169
 170 If the package is properly installed, it will be "stowned" automatically.
 171 ``stowned'' means that this package is available in the master directory,
 172 on which xpbs has symlinked all files from DESTDIR/<pkgname>.
 173  +
 174
 175 To remove a currently installed (and stowned) package, you can use:
 176
 177 -----------------------------------------
 178 $ cd srcpkgs/<pkgname> && xbps-src remove
 179 -----------------------------------------
 180
 181 Please note that when you remove it, the package will also be removed
 182 from XBPS_DESTDIR and previously `unstowned`.
 183  +
 184
 185 To stow an already installed package (from XBPS_DESTDIR/<pkgname>):
 186
 187 ---------------------------------------
 188 $ cd srcpkgs/<pkgname> && xbps-src stow
 189 ---------------------------------------
 190
 191 To unstow an already installed (stowned) package:
 192
 193 -----------------------------------------
 194 $ cd srcpkgs/<pkgname> && xbps-src unstow
 195 -----------------------------------------
 196
 197 You can also print some stuff about any template build file, e.g:
 198
 199 ---------------------------------------
 200 $ cd srcpkgs/<pkgname> && xbps-src info
 201 ---------------------------------------
 202
 203 To list installed (stowned) packages, use this:
 204 ---------------
 205 $ xbps-src list
 206 ---------------
 207
 208 To only extract the distfiles, without configuring/building/installing:
 209
 210 ------------------------------------------
 211 $ cd srcpkgs/<pkgname> && xbps-src extract
 212 ------------------------------------------
 213
 214 To not remove the build directory after successful installation:
 215
 216 ---------------------------------------------
 217 $ cd srcpkgs/<pkgname> && xbps-src -C install
 218 ---------------------------------------------
 219
 220 To only fetch the distfile:
 221 ----------------------------------------
 222 $ cd srcpkgs/<pkgname> && xbps-src fetch
 223 ----------------------------------------
 224
 225 To only install the package, _without_ stowning it into the master directory:
 226 --------------------------------------------------
 227 $ cd srcpkgs/<pkgname> && xbps-src install-destdir
 228 --------------------------------------------------
 229
 230 To list files installed by a package, note that package must be installed
 231 into destination directory first:
 232 ------------------------------
 233 $ xbps-src listfiles <pkgname>
 234 ------------------------------
 235
 236 That should be enough to get you started. If you have any question or
 237 suggestion about *xbps-src* and the build templates, don't forget that there
 238 is a mailing list to talk about it on:
 239
 240 http://groups.google.com/xbps