Checking Out, Updating and Compiling
Setting up a Build Environment
There are now two different build systems for the php-gtk-doc module;
the standard one, used on the server and having several different build
options, and the alternative one, which currently offers only the English
version of the multiple HTML file build.
The chief advantage of the alternative build is that it makes it
possible to compile the PHP-GTK manual under Windows without installing
a Linux emulator such as cygwin.
You will, however, need to install several native versions of
Unix tools in order
to set up the build environment for it. Installing these simply means
unzipping them into your root directory, so this is an easy option if you
don't have good enough connectivity or are otherwise precluded from
installing cygwin on your local box.
Whichever build option you use, you will need to have
xsltproc installed to process the XSL stylesheets. On
a Linux system, you can install this with your package manager. If you are
working under the cygwin environment, you can add it via the cygwin install
mechanism. If you're using plain Windows, you can download the xsltproc
binaries (you'll need the iconv, zlib, libxml2 and libxslt packages) from
xmlsoft.org contributor Igor Zlatkovic's
and unzip them into your root directory.
There are other XSLT processors around but, since we found xsltproc to be
by far the fastest of the available alternatives, the stylesheets used to
generate the PHP-GTK 2 manual now rely on it entirely.
Before we can start changing or even compiling the manual, we need to get
a copy from SVN. To accomplish this, you will need an SVN client. On nearly
every Linux system, the command line svn tool is
installed. This is also available via cygwin. Under Windows, there are
native point-and-click SVN clients available, such as
To get a copy of the docs using the svn command line
svn checkout http://svn.php.net/repository/gtk/php-gtk-doc/trunk php-gtk-doc
If you already have a copy, you can update it via:
cvs -d :pserver:email@example.com:/repository update -Pd php-gtk-doc
(if you are inside the php-gtk-doc directory, you can (have to) omit the
To obtain a copy of the docs module using TortoiseCVS: go to
File/CVS checkout and fill out the form. The protocol
is the Password server (:pserver) option; the server is
cvs.php.net, and the repository folder is
/repository. If you have a CVS account, please use your
own user name; otherwise, use cvsread; and the module,
of course, is php-gtk-doc. Under the current version
of TortoiseCVS, the line endings are converted to Windows by default; we
don't want this anywhere in the php.net repository, so if you're intending
to commit any of your changes you should go to Options
and tick the box that says Use UNIX line endings.
Compiling the Standard Build
From the commandline, move into the php-gtk-doc directory via the command
cd php-gtk-doc. Type autoconf to set
up the configuration file.
There is full internationalisation (i18n) support in this build system,
with the default configuration being English (en). If you are compiling
for any language other than English, you will need to supply the configure
line with the language code for that language, e.g.
./configure --with-lang=de. Note that this will only
work if the base files for the German translation happen to exist!
Another configure option you may need to use is
--with-php=PATH, where PATH is the
full path to the PHP binary executable you intend to use. In most cases,
the PHP 4 or PHP 5 binary found automatically by autoconf will be fine
- but occasionally people have strange setups on their systems. You really
should be using CLI for building, by the way, but CGI will generally cope.
You can prevent the chunked builds (html,
phpweb, test) from telling you
every time they write a file by using --disable-output.
In theory at least, this should speed up the build time for those versions.
There is one last configuration option, --with-history,
which you may or may not fall across. It's used to define the path to an
external directory containing only manual/* (a snapshot
of php-gtk-doc/manual). This is only used during the
make updates option, which is primarily there to
generate the updated documentation lists on the server. You won't need it.
Finally, there is a choice of output style. Choosing
make bigmanual.html will give you a single, huge HTML
file in less than five minutes; make text will do the
same, but will also produce a copy of the manual as a single text file
at the end of the build run. make html will eventually
produce multiple HTML files in split directories alongside a copy of the
images directory; make phpweb will
result in a copy of the manual as it appears on gtk.php.net. By popular
demand, there is now also make test id=ID, where
ID is the manual id for a component, e.g.
or gtk.gtkwindow. This will build the relevant file -
and anything below it in the hierarchy - into a toplevel directory named
testbuild rather than into build.
There are two output types you are very unlikely to need at all:
make mtoc, which generates a machine-readable table of
contents in XML, and make updates, which is used on the
build server to generate the manual updates list for the home page at
Further output formats are likely to become available in the near future.
Compiling the Alternative Build
From the commandline, change into the php-gtk-doc directory via the command
cd php-gtk-doc. Now set up some basic
files: ./runfirst.sh (or
sh ./runfirst.sh if you are working under Windows). The
runfirst-script has only to be called again if
completely new files have been added to the manual, or if the build date
needs to be updated. So if you want to compile the manual on a daily basis,
you should do that every time.
Let's generate the manual itself: At first you must understand that
the php-gtk manual exists in different languages, in addition to
the different formats mentioned earlier. So when compiling, you
need to know which manual you want to compile. The language is
determined as two-letter code, such as en for
English, de for German and so on. The type
is one of html for the normal html documentation
you can download from gtk.php.net,
phpweb to generate the files like the online docs
at the PHP-GTK site, or test if you want to
compile a part of the files only.
So we call ./gen_manual.sh <language> <type>,
for example ./gen_manual.sh en html. You will see
the lines flowing over the terminal; go somewhere and come back in ten
minutes - it will take some time. The files will be generated in the
build directory build/<language>/<type>/,
in our case build/en/html/
If you are an editor and just want to test if the section you just
wrote is correct and renders as intended in html, you can call
./gen_manual.sh <language> test <id>,
as in ./gen_manual.sh en test gtk.gtkiconview.
This will enable a special mode in which the manual will be stripped
down to a minimal version containing only the most necessary things
to compile this special page (id). However, the script is not perfect
and can (currently) generate reference files only, and in this many
links just won't work.
If you have an Apache webserver with PHP installed, you can use livedocs:
Open the live.php in your browser (on the webserver,
not the local directory itself!) and browse through the manual - the pages
are created on demand, most times as fast as 1 to 2 seconds.