README Updated June 23, 1999
gbuild script environment
by Stephen Rust <steve@tp.org>
Current version = 0.6
Table of Contents (TOC)
I. Introduction
II. Distribution Files
III. Current Features
IV. TODO
V. gbuildrc syntax
VI. Examples
I. Introduction
gbuild was created to automate the build process when checking out new cvs code and compiling it for gnome. It was created because no tools that I currently found available did the job that I wanted done, namely: easy to work with, powerful, and possible to have the entire process automated from cvs checkout --> compile --> tar file --> rpm.
The current tools such as CvsToRPM or gnometool were both good for their functions but didn't offer the whole package.
It is hoped that this gbuild package will be useful to you. It seems robust enough to work in a variety of ways. It is not perfect and will not work for all cases, but should work quite well in most cases. If there are problems that you find, or features that you would like to see, or trouble with some of the features please don't hesitate to let me know. I should be reachable at <mailto:steve@tp.org>. I want to make it as bug-free was possible so it can be usable in nearly all situations.
II. Distribution Files
gbuild/README -- This README file gbuild/AUTHORS -- List of Contributors to gbuild gbuild/ChangeLog -- The list of latest changes gbuild/INSTALL -- INSTALL notes on installation gbuild/data/PARTS -- PARTS file the module list. One module per line. gbuild/data/gbuildrc -- A sample .gbuildrc file. Copy to $HOME/.gbuildrc gbuild/scripts/autospec -- Perl script used to auto-create .spec files gbuild/scripts/gbuild -- the main gbuild script
gbuild/scripts/geninstallfiles -- generates file list for a module gbuild/scripts/gbuild-config -- current gbuild install info
gbuild is now using the automake/autoconf system. The scripts are generated at configure time. The default install location will be /usr/local. The scripts will be installed in $prefix/bin, and all other data files will be placed in $prefix/share/gbuild. This includes the PARTS file, sample gbuildrc, this README file, and the directories of log, rpm, spec, srpm, and tar.
NOTE: For users who don't have write permission to the gbuild install location, $HOME/.gbuild will be used as the equivalent to $prefix/share/gbuild. Meaning, that on a per-user basis, the log, rpm, spec, srpm, and tar files built by that user will be placed in this place in their home directory. Also, the PARTS file if placed in $HOME/.gbuild/PARTS will override any system defined parts located in $prefix/share/gbuild/PARTS. This allows for any user to customize their PARTS file without needing to have write access to the system default.
NOTE2: I will refer to $ioprefix as $prefix/share/gbuild or $HOME/.gbuild or the directory specified in the -sd option, throughout this file.
The following files are created when gbuild is run. They are placed in the $ioprefix/log directory. In other words, they are placed in $prefix/share/gbuild/log if you have write access to that directory when running gbuild, or are placed in $HOME/.gbuild/log. Also, you can specify the directory explicitly. See the -sd option below.
AUTOGEN.<name>.LOG -- All configure, make, make install output
goes here. The package name you are compiling
for is put in place of <name>.
COMPILE.LOG -- A log description of what modules were
compiled when, and if they were successful.
III. Current Features
gbuild accepts the following command-line options:
-h, --help
View the command line options help screen.
Shows a brief description with -h, or a longer
description with --help.
-version, --version
Show gbuild version information
--norc
Bypass the rc file. This option is used mainly by
gbuild itself when recursive calls are made to setup
the variables correctly. Untested when using it
manually yourself.
-v
Verbose operating mode
This will show the processing that occurs of the command
line arguments. Each step of the processing will be
described step by step as things go along.
-V
Extra verbose mode
This function doesn't currently do much. The idea is
to print the Autogen, and compile output to the screen
as well as to the output files.
-d <directory>
Specify a working directory
Use this option to specify where the code to compile is,
or where to place code that is updated through cvs.
This is the directory where all the modules' directories
are located or will be located. If the sub-directories of
your current directory is not where the modules are
located, supply this option to tell gbuild where to look.
This is one of the more important options, as it is
necessary to be looking in the right directory for what
you want done. See Examples section below for better
clarification
-sd <directory>
Specify directory for I/O files
This sets the $ioprefix for gbuild.
The directory specified by -sd is usually the base
directory of gbuild. This directory should contain
the PARTS file, the spec directory, the tar directory,
the log directory, the rpm and srpm directory.
The default search order uses $prefix/share/gbuild if you
have write access to that directory, or secondly
$HOME/.gbuild, or the dir specified with the -sd option.
-cd <directory>
Specify the compile directory.
The package will be copied (archived: cp -au) to the compile
directory. This insures that the code is pristine where it
is downloaded, and any object files are placed in a separate
space. Its generally a good idea to use this option.
-co <commands>
Specify checkout option.
By default, -co is set to 'checkout'.
This option is used to specify the cvs option on how to checkout
or update the code. Can specify update, checkout or any variations
of the CVS commands. Usable to checkout specific versions of the
packages and similar capabilities.
Common choices include: -co checkout, -co update, -co update -d
Or for the case of a specific version: -co update -r 1.1
-u [module list]
Perform CVS update of code
This is one of the main gbuild options.
With no modules listed after the -u option, the PARTS file will be
used to get the module names.
gbuild will attach to the cvs server specified in
shell environment variable CVSROOT (by running cvs) and
will use the command specified with the -co option. The modules
specified on the command line, or in the PARTS file, will
be updated. Any number of modules to update can be supplied
after a -u option.
See Examples section below.
-c [module list]
Perform compile of code
This option runs autogen.sh or configure (or make if those
aren't found), then runs make, and then make install on
the specified modules.
gbuild will enter the directory specified by the -d option
(or the current directory, if no -d option is given) and
attempt to compile. It will try autogen.sh, configure, or
just plain make, in that order, using the first one that
exists, or returning an error if none of the 3 work. Any
number of modules to compile can be supplied after a -c.
If no modules after the -c option are given, the PARTS variable
will be set from the .gbuildrc or the default PARTS file found
in the ioprefix directory. See -sd above.
-opt <option-list>
specify an optlist to pass to the compile line.
Use this option to supply additional parameters to
autogen.sh or configure. Any number of parameters can
be supplied after a -opt. Some examples include:
-opt --prefix=/opt/Package --disable-static
and others.
--tar
Supply this option in conjunction with the -c option to
build a tar file of the code. The tar file is placed
in $ioprefix/tar. It basically runs a 'make dist'
command on the module.
--spec
Use the autospec perl script to build a .spec file of the
module. This option can only be used if the -c option is
also specified. The resultant spec file will be placed
in $ioprefix/spec.
The spec file search order will first look in $ioprefix/spec,
and then in the module directory for one that might have
been distributed with the module itself. If you want to use
the spec file distributed with the module, don't use the
--spec option. Otherwise, if a spec file exists in
$ioprefix/spec for that module the one distributed with the
package won't be used.
--rpm
Build an rpm file of the modules. This option can
only be used along with the -c option. The module
code is installed in a temporary working space, and
the rpm is created without doing another build of the
code. The resultant rpm file will be placed in
$ioprefix/rpm. This option builds only a binary rpm,
not an srpm. A very stripped down spec file is
created and used so none of the prep, build, or other
rpm options are used at all during the building of the
rpm.
--srpm
Same as the --rpm option, only builds both binary rpm
and source rpm (srpm) files
--init
If you don't have write access to $prefix/share/gbuild
you will get a message back telling you to use the --init
option. This will create the $HOME/.gbuild directory
structure, creating the log, rpm, spec, srpm, and tar
directories in your home directory.
--tmp <directory>
Allows you to specify the tmp directory for tmp working
space. By default, the /tmp directory is used.
--includes <options>
The includes add to the GLOBAL options specified in the
.gbuildrc file. It is ':' delimited options list adding
package specific parameters to use when building a specific
package. This option can also be supplied in the .gbuildrc
file as the INCLUDES variable. Its recommended to use the
.gbuildrc file instead of supplying these type of options
on the cmdline. See the gbuildrc section for more.
--excludes <options>
The 'excludes' remove items from the GLOBAL options specified
in the .gbuildrc file. It is used to remove options for a
specific package. For example, if you want to compile
everything with a certain option, but remove that option for
one specific package. See Examples section below. This option
can also be supplied in the .gbuildrc file as the EXCLUDES
variable. See the gbuildrc section for more.
--replace <options>
The 'replace' options replaces package specific options with new
fields. For example, if you want to install all packages except
for one or two into the same location on your drive, specify this
option to change the install location for those few specific
packages. See Examples section below. This option can also be
supplied in the .gbuildrc file as the REPLACE variable. See the
gbuildrc section for more.
IV. TODO
- Implement the -V extra verbose option. Currently does nothing.
- Parse Makefile.am or similar file so we can build dependency lists and automatically choose the order of building packages, given a list.
- Run all builds, and dependency checks, without actually doing an install. This is important, as we aren't always able or wanting to install the packages right away.
V. gbuildrc syntax
There are usually 3 main variables that should be set in the .gbuildrc. This includes the GLOBAL variable which applies options to every module, the INCLUDES variable which applies options to specific modules, the EXCLUDES variable which removes options from specific modules, and the REPLACE variable which does a string replace on an option for specific modules.
The variables are set with a string, with each module's options of INCLUDES, EXCLUDES, REPLACE separated by newlines or tabs. Use spaces inside of the : options to specify more than one option for the module on the same line.
The module name and its options are separated by a :
#.gbuildrc:
GLOBAL="-opt --disable-static --prefix=/usr/local -d/home/cvs -cd/home/compile"
INCLUDES=" imlib:--tar
gimp:--spec --rpm
esound:--spec --rpm"
EXCLUDES=" ORBit:--disable-static"
REPLACE=" gimp:--prefix=/usr/local:--prefix=/opt/gimp"
# end .gbuildrc
Stepping through this file line by line. We first have the GLOBAL option. The line of GLOBAL will apply all the gbuild options to each module. Any standard gbuild option can be supplied here in the GLOBAL variable. It is the equivalent of supplying each of those options on the cmdline.
The INCLUDES variable is set next. the syntax is:
<module-name>:<options>
the 'imlib:--tar line' will add the --tar gbuild option only for the imlib module. the 'gimp:--spec --rpm' line will add the --spec and --rpm options only for the gimp module. the 'esound:--spec --rpm' line will add the --spec and --rpm options for the esound module.
Each of these 3 lines are separated only by newlines and by tabs. Specific options, like in the gimp & esound lines are separated just by spaces between the --spec and --rpm options.
The EXCLUDES variable is set next. the syntax is:
<module-name>:<options>
'ORBit:--disable-static' removes the global option --disable-static which was set in the GLOBAL settings, for the module ORBit. ORBit can't compile with this option, so this allows us to remove the option for the specific module ORBit but still compile all our other modules with the --disable-static option.
The REPLACE variable is next. The syntax is:
<module-name>:<current-string>:<replace-string>
If you're familiar with sed search and replace syntax, this option works the same way. Whatever is placed in the '<current-string>' part, will be replaced with whatever is in '<replace-string>' for the module name '<module-name>'. In this case, we want to install gimp in a different location so we change the prefix line from: --prefix=/usr/local to --prefix=/opt/gimp.
There is no limit to how many different modules you can supply inside of the options.
A default setup is installed as $prefix/share/gbuild/gbuildrc. Copy, and edit that file to your specifications into $HOME/.gbuildrc
VI. Examples
Q) Compile all modules from PARTS
gbuild -c
Q) Compile all modules, building spec files, tar files and rpms
gbuild -c --spec --tar --rpm
Q) Compile glib module located in subdirectory gnome
gbuild -d gnome -c glib
Q) Update and then compile glib located in subdirectory gnome
gbuild -d gnome -u glib -c glib
Q) Update lots of modules, only compiling a few
gbuild -d gnome -u glib gtop imlib ORBit -c gtop imlib
Q) Update gnome module into current directory
gbuild -u
Q) Update a module, Compile it, build a tar file, build the spec
file, then build an rpm
gbuild -u glib -c glib --tar --spec --rpm
Q) Compile gnome-libs with --prefix=/opt/gnome option.
gnome-libs is located in the /opt/gnome-compile directory
gbuild -d /opt/gnome-compile -c gnome-libs -opt --prefix=/opt/gnome
Q) gbuild root is not the current working directory, its in
/home/user/gbuild. modules need to be checked out in another
subdirectory also, /opt/gnome.
I need a tar file of imlib, ORBit, and gtk+
gbuild -d /opt/gnome -sd /home/user/gbuild -c imlib ORBit gtk+ --tar
Q) Specify checkout option
gbuild -u gnome-libs -co checkout -r GNOME_STABLE
Q) Don't use --disable-static with ORBit, even though we specified --disable-static
in the .gbuildrc file as a GLOBAL option.
gbuild -c ORBit --excludes ORBit:--disable-static
Q) Install gimp in /opt/gimp, even though we specified /opt/gnome as the default
install location in the GLOBAL option of the .gbuildrc file.
gbuild -c gimp --replace gimp:/opt/gnome:/opt/gimp
VII. Feedback
Please contact me with questions, bug-reports, or general feedback regarding gbuild. Gbuild's home is currently http://www.cryon.com/gbuild. Email contact is: steve@tp.org
Thanks and enjoy!
Steve