Replace README with an asciidox txt file used in webpage.

--HG--
extra : convert_revision : 2be400f70013d96d132710978c02ab9ad0980e2a

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/
+  xbps-templates/
-     |
+      |
-     |----- srcpkgs/
+      |-----srcpkgs/
-             |
+               |
-             |----- binutils/
+               |-----binutils/
-             |----- gcc/
+               |-----gcc/
-             |----- glibc/
+               |-----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/<pkgname>.
  +
+ +
 
 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/<pkgname>):
+
 ---------------------------------------
-$ 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