README Updated June 23, 1999

gbuild script environment
by Stephen Rust 
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 .  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			-- generic 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..LOG	-- All configure, make, make install output
			   goes here.  The package name you are compiling
			   for is put in place of .  
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 

		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 

		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 

		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 

		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 

		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 

		Allows you to specify the tmp directory for tmp working
		space.  By default, the /tmp directory is used.

	--includes 

		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 
	
		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 

		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:

	:

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:

	:

'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:

	::

If you're familiar with sed search and replace syntax, this option works the same way.
Whatever is placed in the '' part, will be replaced with whatever is in
'' for the 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