.\" $Id: README.mdoc,v 1.23 2004/05/14 21:37:12 jmmv Exp $
.\"
.\" buildtool
.\" Copyright (c) 2002, 2003, 2004 Julio M. Merino Vidal
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of the author nor the names of contributors may
.\"    be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
.\" PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR
.\" OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"/
.ds volume-operating-system
.ds volume-ds-1 Buildtool Distribution Information
.Dd May 14, 2004
.Dt README 1
.Os BSD
.
.Sh NAME
.
.Nm README
.Nd Buildtool installation process description
.
.Sh WELCOME TO BUILDTOOL
.
Buildtool is a portable build infrastructure.
From developer's point of view, it provides all tools needed to create
powerful source code autoconfiguration scripts and simple makefiles.
For the user, this simplifies the process of building and installing
third party packages in his own system.
.Pp
You are encouraged to read this document entirely before starting to
play with the Buildtool package, as it contains several things you
need to know beforehand.
.Pp
Remember that you can get the latest Buildtool version, read the
manual online and get free support from the official website:
.Bd -literal -offset indent
http://buildtool.sourceforge.net/
.Ed
.
.Sh LICENSE
.
Buildtool is licensed under the terms of the BSD license.
Please read the
.Pa COPYING
file for more details on this topic.
.
.Sh BUILDING AND INSTALLING
.
Buildtool's build process can be summarized as follows: configure the
sources, build them and install the results.
.Pp
If you have trouble during the process, the section
.Sx SYSTEM SPECIFIC NOTES
contains some tips that may help you.
.
.Ss Configuring
.
Source code configuration is done by the configure script, in a
completely automated way.
At a very minimun you will need a C compiler, like
.Xr cc 1 ,
a
.Xr make 1
tool, a
.Xr sh 1
interpreter, a lexical analyzer generator, like
.Xr lex 1 ,
and a LARL parser generator, like
.Xr yacc 1 .
All these tools are standard, so you shouldn't worry about them.
If the script is unable to find any of them, it will stop and give
you a chance to solve the problems.
You can easily launch the configure process by issuing:
.Bd -literal -offset indent
$ ./configure
.Ed
.Pp
This is the simplest use of this script, which will work most of the
times.
Although there are many user-configurable options that you can look
at using the
.Fl h
command-line switch.
Probably, the most used flag is
.Fl p ,
which specifies the installation prefix.
The script will also create several makefiles, ready to be parsed by
.Xr make 1 .
.\" .
.\" .Ss Disabling features
.\" .
.\" The configure script allows you to optionally disable some Buildtool
.\" features.
.\" Note that features are not automatically disabled, even if they
.\" cannot be build; this tries to solve side effects in prepackaged
.\" software.
.\" Features can be disabled using the
.\" .Fl n
.\" flag, as follows:
.\" .Bd -literal -offset indent
.\" $ ./configure -n feature_name
.\" .Ed
.\" .Pp
.\" Where
.\" .Ql feature_name
.\" can be one of these:
.\" .Bl -tag -width "wrapper"
.\" .It compat
.\" Disable compatibility stuff with previous versions.
.\" This option must be used by developers to see if their packages work
.\" perfectly with that specific version of the program.
.\" Never use this option to build a Buildtool binary package.
.\" .It wrapper
.\" Do not build nor install the Buildtool wrapper.
.\" .El
.
.Ss Building
.
You can start the build by issuing:
.Bd -literal -offset indent
$ make
.Ed
.Pp
Generated makefiles should work with any
.Xr make 1
flavour, as they do not use any kind of advanced features.
Environment variables will not affect this step.
If they contain incorrect values, you will need to set them in the
environment and execute the configuration script again.
.
.Ss Installing
.
The installation is as simple as all other steps.
Depending on the prefix you chose while configuring sources, you will
need to be
.Ql root
to do this step (note that you can do the installation as a regular
user if you have enough privileges on the target directory).
Issue:
.Bd -literal -offset indent
$ make install
.Ed
.Pp
And that's all!
If you used a non-standard prefix you will want to setup your path
accordingly.
No other change is required in your environment, as Buildtool
remembers where it was installed and calls its modules with full paths.
.
.Ss What to do if build fails
.
If the build process fails in some step, please report it!
We must know the problem in order to solve it.
.Pp
The first thing you must do to provide a good bug report is to take a
log of all the process you did.
To achieve this you can use the
.Xr script 1
command; this utility starts a subshell where you can run commands (as
you usually do), but all output is redirected to a log file.
.Pp
As a summary, you should do something like this (note that output is
removed for simplicity):
.Pp
.Bd -literal -offset indent
$ script build.log
Script started, output file is build.log
$ uname -a
$ make cleandir
$ ./configure -p /tmp/debug
$ make
$ make install
$ exit
Script done, output file is build.log
.Ed
.Pp
Once this is done, send me the
.Pa build.log
file, at the following email:
.An Julio M. Merino Vidal Aq jmmv@users.sourceforge.net .
If you can add additional information to this log (that you think
can be useful to us), please do so.
.
.Sh SYSTEM SPECIFIC NOTES
.
This section contains several notes about building and installing
Buildtool on specific systems.
.
.Ss Win32 (using Cygwin)
.
Buildtool can work under Win32 systems using the Cygwin environment.
You can download the installer from:
.Bd -literal -offset indent
http://www.cygwin.com/
.Ed
.Pp
When you are asked to select which packages you want to install,
select (aside from the defaults): bzip2, cygutils, less, make and gcc.
.
.Sh USING BUILDTOOL
.
All Buildtool commands are run through a small wrapper which selects
the appropiate module and its flags each time.
To read a brief summary of commands, issue:
.Bd -literal -offset indent
$ buildtool -h
.Ed
.Pp
If you are an end-user, who only needs to use Buildtool to configure,
build and install third party programs, you will not need to learn
many details.
Start by reading the
.Pa README.bt
file included in any Buildtoolized package.
All further instructions are included there, as well as some
documentation references.
.Pp
If you are a developer interested in using Buildtool in your own
programs, you will need to learn and understand several concepts.
The installed
.Xr buildtool 1
manpage provides a good starting point.
The
.Pa http://buildtool.sourceforge.net/docs.html
page contains all information available.
.
.Sh TESTING
.
As Buildtool is still in alpha development state, it is very important
that you do some basic testing.
Buildtool comes with Buildtool's TestSuite, a sample package designed
to see how Buildtool performs in your system.
.Pp
To start the testing process, launch the following command from the
directory where you built Buildtool:
.Bd -literal -offset indent
$ make test
.Ed
.Pp
Remember that you will probably need less than 10 minutes to read the
file and do all the tests.
But you will be helping us a lot by providing porting related
information.
.
.Sh SUPPORT
.
For technical support subscribe and post to Buildtool's mailing lists.
See
.Pa http://buildtool.sourceforge.net/mlists.html
for a list of available lists.
.
.Sh AUTHORS
.
This document was written by Julio M. Merino Vidal.
For a complete list of authors and contributors, please look at the
.%T PEOPLE
file included with Buildtool's distribution.
.\" Local Variables: ***
.\" mode: nroff ***
.\" End: ***
.\" vim: syntax=nroff