

1. Notes on the use of INSTALL_TYPE

2. Passing options to the 'configure' script

3. Building packages as a normal (non-root) user

4. Controlling execution using the --pause or --resume options

5. Building packages for multi-lib systems

6. Building packages with a prefix besides '/usr'

=====================================================================================

1. Notes on the use of INSTALL_TYPE
	One very important variable used by src2pkg is called INSTALL_TYPE. This
	refers to the way in which package content gets created using the
	'fake_install' instruction or function. fake_install is a 'front-end'
	to whatever command is normally used to install software to your system
	-usually the command 'make install'. fake_install provides 5 distinct
	methods to run the installation commands -usually without installing
	the items at all. fake_install tries to run the commands while re-directing
	them so that software gets installed into an alternate location -the PKG_DIR.
	Two of the INSTALL_TYPES are available to non-root users: '-DESTDIR' (or '-DEST')
	and '-JAIL'. Three more types can only be used while running src2pkg as
	root: '-REAL', '-SAFE' and '-UNION'. The '-UNION' option sets up a small
	chroot environment using fuse and unionfs. Software is installed into
	the chroot environment so it can be isolated from the real system
	directories. As implied, the REAL option actually installs the software
	to your system, but creates a log of all files created or modified, then
	copies them into the PKG_DIR and finally removes them from the main
	filesystem. However, this can overwrite files which are already on your
	system. Using the '-SAFE' option avoids changes to your system, by creating
	backups of any files which would be overwritten, and then restoring them
	once the new files are copied into the PKG_DIR.
	
	The REAL and SAFE methods are the most accurate and dependable methods,
	but unfortunately they are the most intrusive as they don't even try
	to re-direct the output of the installation commands. For that reason,
	we recommend only them only when none of the other methods work.
	
	By default, src2pkg will use the JAIL method for content creation. For
	a long time, the DESTDIR method was the default as many people are familiar
	with it and trust it. However, DESTDIR is not very dependable and will often
	write some files correctly to the DESTDIR(PGK_DIR), but will try to write
	other files to the main system directories. This means that, if running
	as root, you will have 'orphaned' files on your system which are not
	included in the package, or if running as a normal user, then the commands
	will fail. Failing is better than creating orphaned files, but since the
	failure stops the src2pkg build process, the user is left without a 
	package. Usually, the JAIL method will succeed in these cases. The JAIL
	method will also fail sometimes, for reasons which are difficult to
	discover or explain. But it makes a safer default than DESTDIR and will
	not fail more often than DESTDIR.
	
	One of the most common failures when trying to create a package is when
	INSTALL_TYPE is not usable for that package. If your package build fails
	with an error like: "Running 'make install' has failed with error:"
	or you see this: "Possible error running 'make install'"
	the first thing to do is to try building the package using one of the other
	INSTALL_TYPE options. This will usually allow for the package to be
	properly built. You should also try this if you notice that some files
	are not being included in the package which you are sure should be in it.
	
2. Passing options to the configure script
	For compiling some sources, you'll want or need to pass extra options
	to the configure script to enable or disable program features. Of course,
	src2pkg provides a way to easily do this, either using command-line
	options or by including the extra options in a src2pkg script. Let's
	take an example where you want to build and package a certain program,
	but need to pass some extra options like: --disable-gnome --with-x
	When normally configuring such sources you'd use a command like this:
	./configure --prefix=/usr --disable-gnome --with-x
	When using src2pkg, the prefix option is separate and defaults to /usr,
	so normally you shouldn't have to worry about it. The command-line
	for doing the above using src2pkg would look like this:
	src2pkg -e='--disable-gnome --with-x' tarball-name
	If you really wanted to use a prefix besides /usr, supply it separately:
	src2pkg -p='/usr/local' -e='--disable-gnome --with-x' tarball-name
	You can also use the "long form" of the src2pkg syntax, like this:
	src2pkg --pre_fix='/usr/local' --extra_configs='--disable-gnome --with-x' tarball-name
	
	If you are using a src2pkg script to build the sources with, you should
	use the same syntax that src2pkg uses for its' internal API:
	PRE_FIX=/usr/local
	EXTRA_CONFIGS="--disable-gnome --with-x"
	(Be sure to use quotes if the options contain spaces).
	
	You don't have to learn all the internal syntax in order to be able to use
	a src2pkg script, as src2pkg will write the script for you with the correct
	syntax for any options you give on the command-line. This command:
	src2pkg -p='/usr/local' -e='--disable-gnome --with-x' -N tarball-name
	The '-N' option tells src2pkg to create a new src2pkg script for you,
	and the extra options you passed will be written into the script with
	the correct internal syntax as shown above.
	
	The '-e=??' (or EXTRA_CONFIGS) option can also be used to pass options
	to other configuration methods, including those used for compiling
	perl-modules or sources which use 'cmake' for configuration.
	
3. Building packages as a normal (non-root) user		               ####
	Most software can be built with src2pkg while running as a non-root,
	non-privileged user. In these cases, src2pkg uses the owner/group commands
	of 'tar' to set the ownership and group of all files to 'root', so
	the package can be installed normally to your system. However, there
	are cases where this is not the desired result. For instance, some software
	installs files or directories which belong to a specific non-root user,
	particularly server or daemon software which may run at boot-time. In
	these cases you have two options: build the package as root so that
	the correct onership and permissions are preserved, or include lines
	in a doinst.sh script which set the owner/group/perms when the package
	gets installed.
	
	Also, there are a few cases where neither the JAIL or DESTDIR options
	(described above) will work to create the package content. In such cases,
	the package must be built as root, using one of the other INSTALL_TYPE
	options.
	
	rpm packages should usually not be built as a non-root user as rpmbuild
	will set the 'owner' and 'group' of all files to the normal user.

4. Controlling execution using the --pause or --resume options		####
	You can control the flow of execution of src2pkg using the options
	'--resume=??' and/or '--pause=??'. These options are not meant to
	be used so that you can do things manually inside the sources or
	in the package-tree content while execution is paused. When resuming,
	src2pkg will automatically clear out any previously-created content
	in the package tree.
	
	The 'resume' is especially useful when working with sources which
	take a long time to compile. You may want to interrupt a build which
	is taking more time than you have. It is also useful if you are
	creating more than one type of finished package. To use the resume
	option, simply give the name of the src2pkg function or build
	instruction where you want src2pkg to resume at -for example:
	src2pkg --resume=compile_source
	will resume the build at the compile_source function. You can see
	a list of the functions where builds can be resumed, by running 
	'src2pkg --list'
	
	Usage of the 'pause' option is similar. By using 'pause', you can
	have src2pkg pause before or after each step of the build. Or you
	can have it pause at just one build step. To pause before or after
	every step, use the pause option like this:
	src2pkg --pause=after (or --pause=before)
	Or, to have src2pkg pause at a single step, use the name of the
	function or build instruction, as above:
	src2pkg --pause=fake_install
	As above, the command 'src2pkg list' will show you the list of
	functions available for pausing. When used this way, the 'pause'
	option will both before and after the named function.

5. Building packages for multi-lib systems
	src2pkg makes it very easy to build packages for multi-lib systems.
	The most common case for this is with 64-bit systems which also
	have some 32-bit libraries and programs installed. src2pkg provides
	command-line options for easily controlling multi-lib builds. The
	two main ones are the '-M??' and '-L??' options. The -M?? option
	is used to tell src2pkg which 'Machine Option' to pass to the compiler,
	and the -L?? option is used, when needed, to tell src2pkg the library
	path-names to use for configuration and installation of the package.
	The most common case would be something like this: You have a 64-bit
	system with some 32-bit compatibility libraries already installed.
	For most systems, the 64-bit libraries are installed under /lib64
	and /usr/lib64, and the 32-bit libraries are installed under /lib
	and /usr/lib.
	To compile and package a program which uses the 32-bit libraries,
	simply add the option '-M32' to whatever src2pkg options you are
	using. If you are using a system which uses a different directory
	structure, you can use the -L?? option to control the path-name
	to use. The most common options are avilable as simple 'switches':
	-M32, -M64, -L32, -L64 (and -L0 or -LNULL). But there is also a
	long-form syntax which can be used for creating packages using
	a cross-compiler. Instead of the -M?? option as shown above,
	you can use: --machine=??; and for the -L?? option: --libdirsuffix=??
	Using the long-form syntax lets you specify any sort of directory
	name and/or gcc 'Machine Option' needed.
	
6. Building packages with a prefix besides '/usr'
	Ordinarily src2pkg configures sources using the default --prefix=/usr
	Many of the sanity checks and corrections done to the package content
	assume that the prefix is '/usr', unless special steps are taken.
	src2pkg has an option setting called FHS_POLICY that is used to tell
	it where certain files should be located on the system -like man-pages
	info pages, documents and others. The default setting is:
	FHS_POLICY=SLACK
	The other standard option is: FHS_POLICY=LSB
	They are similar except for minor differences where Slackware uses
	paths which are different than what the Linux Standards Board recommends.
	But, if you usually build packages which are meant to install under
	/usr/local or other non-standard paths, you may find that some of
	the src2plg correction routines make it hard to get all the files
	installed under the prefix you have specified. If that is the case,
	then you should use FHS_POLICY=NONE so that src2pkg doesn't force
	items to be installed to the 'standard' locations. You can change
	the FHS_POLICY from the command line by running src2pkg like this:
	FHS_POLICY=NONE src2pkg ....
	Or, you can change the default setting by editing your src2pkg.conf
	file. Look for the line with the FHS_POLICY variable and uncomment
	it by removing the leading '#' character and editing it to this:
	[[ $FHS_POLICY  ]] || FHS_POLICY=NONE
	This will still let you override that setting from the command-line
	as shown above:
	FHS_POLICY=?? src2pkg ....
	Otherwise, the new default FHS_POLICY=NONE will be used.
	