Add a couple of exceptions to .gitignore

[packages] / xemacs-packages / build / build.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename build.info
@settitle XEmacs Build Reference Manual
@dircategory Emacs
@direntry
* Build: (build).      Build XEmacs from within (UNIX, Windows).
@end direntry
@c footnotestyle separate
@c paragraphindent 2
@c %**end of header
@setchapternewpage odd
@ifinfo
This document describes the XEmacs package called build.
Copyright @copyright{} 2000-2002 Adrian Aichner.
@end ifinfo

@c @c Combine indices.
@c @synindex cp fn
@c @syncodeindex vr fn
@c @syncodeindex ky fn
@c @syncodeindex pg fn
@c @syncodeindex tp fn

@titlepage
@c @sp 10
@c @comment The title is printed in a large font.
@c @center @titlefont{Build}
@c @c The following two commands start the copyright page.
@c @page
@c @vskip 0pt plus 1filll
@c Copyright @copyright{} 2000-2002 Adrian Aichner.
@title XEmacs Build Reference Manual
@subtitle Version 2.00 (for XEmacs 21.1, 21.4, 21.5), dated 2002-03-07

@author by Adrian Aichner
@page
@vskip 0pt plus 1filll
@sp 2
@c Version 3.3 @*
@c Revised for XEmacs Versions 21.0,@*
@c April 1998.@*

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU General Public License'' is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU General Public License'' may be
included in a translation approved by the Free Software Foundation
instead of in the original English.
@end titlepage
@node Top, Build Overview, , (dir)
@comment node-name, next,          previous, up
@chapter Build Package

This is the XEmacs Build Reference Manual, Version 2.00 (for XEmacs
21.1, 21.4, 21.5), dated 2002-03-07, by @email{adrian@@xemacs.org,
Adrian Aichner}.

@menu
* Build Overview::                    Overview of build package
* Build Installation::                Installation of the build package
* Build XEmacs::                      Choosing source and tools          
* Build XEmacs From CVS::             Fetching sources with CVS
* Build XEmacs From Tarballs::        Fetching source tarballs with EFS
* Build XEmacs With GNU Tools::       UNIX-style build using configure, make
* Build XEmacs With Microsoft Tools:: Microsoft build using MS VC++ >= 4.0
* Generate XEmacs Build Report::      Reporting Success or Failure
* Known Problems of Build::           Problems, Workarounds, and Fixes
* Concept Index::                     An item for each concept
@end menu

@node Build Overview, Build Installation, Top, (dir)
@comment node-name,     next,          previous, up
@chapter Build Overview
@cindex What build is

@code{build} supports the building process of the XEmacs editor from its
sources.

@cindex XEmacs build process

The build process consists of following steps:

@enumerate

@item
Download source code from FTP server or CVS repository.

@item
Configure any attributes of the build process, of the resulting XEmacs
executable, and of the XEmacs environment.

@item
Start the make process to build XEmacs, install it, and run the
regression tests.

@item
Report on the success or failure of the build, using build-report.

@end enumerate

The @code{build} command generates a widget-based interface to configure
and build XEmacs either using GNU Tools (@code{configure}, @code{make})
or Microsoft Tools (@code{nmake} with command-line options (<= 21.2-b32)
or @file{config.inc} configuration file (> 21.2-b32)).

@node Build Installation, Build XEmacs, Build Overview, (dir)
@comment node-name,     next,          previous, up
@chapter Build Installation
@cindex How to install build

You have following three choices to install build (@pxref{Installing
Packages, Installing Packages, , xemacs}):

@enumerate

@item
Use the package GUI:

@itemize @bullet

@item
In XEmacs Release 21.1:

Select a download site under

@example
Options->Manage Packages->Add Download Site
@end example

and after listing available packages with

@example
Options->Manage Packages->List & Install
@end example

install @code{build} with

@example
Packages->Toggle install `build'
Packages->Install/Remove Selected
@end example

followed by starting a fresh XEmacs.

@item
In XEmacs Beta Release 21.2-bXX:

Menus have been re-arranged in XEmacs 21.2.

Select a download site under

@example
Tools->Packages->Add Download Site
@end example

and after listing available packages with

@example
Tools->Packages->List and Install
@end example

install @code{build} with

@example
Packages->Toggle install `build'
Packages->Install/Remove Selected
@end example
  
followed by starting a fresh XEmacs.

@end itemize

@item
Run XEmacs command

@example
@kbd{M-x package-admin-add-binary-package @key{RET} @var{build-package-tarball-path} @key{RET}}
@end example

after tarball download with EFS or ftp.

@item

Extract the build tarball(s) into the xemacs-packages hierarchy from
your favorite shell.

@code{bash}, @code{csh}, @code{ksh}, @code{zsh} come to mind on UNIX
systems; Cygwin's @code{bash}, @code{cmd.exe}, and @code{command.exe}
for Windows 95/98/NT/2000.

@example
@kbd{cd @var{installation-directory}/xemacs-packages;
gzip -dc @var{build-package-tarball-path} | tar -xvf -}
@end example
 
@end enumerate

@node Build XEmacs, Build XEmacs From CVS, Build Installation, Top
@comment node-name,    next,  previous,      up
@chapter Build XEmacs

@cindex Accessing Documentation
@section Accessing Documentation for the Build package

You may want to read through the build package info documentation first.
It is accessible via links to Info- and HTML-documentation from the
initial *Build XEmacs* buffer, which has this:

@example
Visit info documentation for the XEmacs build package in [XEmacs]
or on the XEmacs website at
[http://www.xemacs.org/Documentation/packages/html/build.html]
@end example

@cindex build-settings
@cindex build settings
@section Saving Multiple Build Settings

Build settings, introduced in build 2.00, allow you to save all variable
settings relevant to building XEmacs under a single name.  This saves
time and simplifies the process of building multiple XEmacs versions or
configurations.

@example
Current Build Settings: unknown

[Load] [Delete] build settings: [Value Menu] default
[Save] current build settings as: [Value Menu] String: default
@end example

@cindex Browsing Build Options
@section Browsing Build Options

Global build options can be browsed next.

@example
[Browse Build Options ...]
@end example

@cindex build from
@section What to Build From and Build With

You have to decide what to @emph{build from}:

@enumerate

@item
CVS sources in the XEmacs CVS repository at
@uref{http://cvs.xemacs.org/}.

@item
Tarballs (tar.gz files) on the XEmacs FTP Site
@uref{http://ftp.xemacs.org/pub/xemacs/} or one of its mirror sites.

@end enumerate

@cindex build with
and what to @emph{build with}:

@enumerate

@item
GNU@footnote{Alert readers will note: GNU's Not UNIX!}/UNIX tools using
@code{configure}, @code{make}, and @code{cc}.

@cindex xemacs.mak
@item
Microsoft tools using @code{nmake} and @code{cl}, supported by
@file{nt/xemacs.mak} and, beginning with XEmacs 21.2-b33,
@file{nt/config.inc}.

@end enumerate

These two choices determine which of the following steps will be taken.

@example
[Build XEmacs From CVS Now]
@end example

@example
[Build XEmacs From Tarballs Now]
@end example

As of build version 2.00 a check is performed whether CVS is available.

The user interface to *Build XEmacs from CVS* will only be available if
this test (cvs -v) passes.

The cvs client version installed on your system will be displayed below
following button.

@example
[Build XEmacs From CVS Now]
@end example

Finally either press the button labeled @ref{Build XEmacs From CVS}
or @ref{Build XEmacs From Tarballs}.  Only the button labeled according
to your choice under the @emph{build from:} menu will be active.
See @ref{Build XEmacs} and @ref{Known Problems of Build}.

Each of the following steps allow to return to a previous one with the

@cindex Going Back
@example
[Go Back]
@end example

button to review your choices.

Whether to build from tarballs or CVS sources depends on what the user
wants to do with the sources.

@itemize @bullet

@item
Tarballs are convenient for building a well-defined release of XEmacs.
These tarballs are big and users with slow or expensive network
connections should avoid them.

@code{gzip} and @code{tar} are required for this method.

@item
For users who want to stay in close sync with the development of XEmacs,
especially the Beta releases, create patches against files or whole
directories, CVS is the way to go.

You will obviously need to install @code{cvs} first.

@end itemize

The choice is yours@footnote{unless your access to the Internet is
limited by firewalls or disabled IP ports, you don't have gzip/tar, or
cvs.}.

@node Build XEmacs From CVS, Build XEmacs From Tarballs, Build XEmacs, Top
@comment node-name,    next,  previous,      up
@chapter Build XEmacs From CVS
@cindex Obtaining sources with CVS

The CVS commands to fetch XEmacs source code are run through the XEmacs
@code{compile} command (@pxref{Compilation, , , xemacs}).

The buffers are named uniquely with the current working directory
appropriately set to save the buffers with @kbd{C-x C-w} (@kbd{M-x
write-file}) under the XEmacs source directory.

First you have to login to the XEmacs CVS server.

Please do so by pressing following button.

@example
[CVS Login XEmacs]
@end example

If that fails, please send the message generated in the *Warnings*
buffer to @email{cvs-admin@@xemacs.org, XEmacs CVS Administrator}.

After pressing the 

@example
[CVS Checkout XEmacs]
@end example

button (unless you have
checked out before) and either one of 

@example
[CVS Update XEmacs To Release]
@end example

(as specified with

@example
[Browse Build CVS Options ...]
@end example

) or

@example
[CVS Update XEmacs To Latest]
@end example

(resetting all @pxref{Sticky tags, , , cvs}) you are ready to proceed
with

@example
[Build XEmacs Now ...]
@end example

@node Build XEmacs From Tarballs, Build XEmacs With GNU Tools, Build XEmacs From CVS, Top
@comment node-name,    next,  previous,      up
@chapter Build XEmacs From Tarballs
@cindex Obtaining sources with EFS

The tarballs chosen with 

@example
[Browse Build Tarball Options ...]
@end example

Press

@example
[Download Build Tarball Set]
@end example

to fetch tarballs with EFS, which needs to be installed @footnote{If EFS
is not installed you may obtain these tarballs by other means and
extract them to the configured directory.}, followed by

@example
[Install Downloaded Build Tarball Set]
@end example

to extract tarballs using @code{gzip} and @code{tar} in a
@code{compilation-mode} buffer named accordingly (e.g. ???).

Finally press the button either labeled @ref{Build XEmacs With GNU
Tools} or @ref{Build XEmacs With Microsoft Tools} according to your
choice under the @emph{build with:} menu.  See @ref{Build XEmacs}.

@node Build XEmacs With GNU Tools, Build XEmacs With Microsoft Tools, Build XEmacs From Tarballs, Top
@comment node-name,    next,  previous,      up
@chapter Build XEmacs With GNU Tools
@cindex Build on UNIX
@cindex Build with Cygnus (now Cygwin)
@cindex Build with Cygwin
@cindex configure
@cindex configure.usage
@cindex make
@cindex gcc

Besides GNU make (@code{make}) and GNU cc (@code{gcc}) XEmacs can be
built with the equivalent programs from many UNIX vendors.

The @dfn{configure}@footnote{This shell script is on the top-level of
the XEmacs source tree, see also configure.usage there.} script, which
is run before @code{make}, determines the configuration of your system
and warns about any problems it finds.

@node Build XEmacs With Microsoft Tools, Generate XEmacs Build Report, Build XEmacs With GNU Tools, Top
@comment node-name,    next,  previous,      up
@chapter Build XEmacs With Microsoft Tools
@cindex Build on Windows 95/98/NT/2000
@cindex Build with MS Visual Studio C++
@cindex nmake
@cindex cl
@cindex config.inc

XEmacs is built using Microsoft's version of @code{make}, @dfn{nmake},
and Microsoft's C++ compiler, @dfn{cl}, which are both part of Microsoft
Visual Studio @footnote{Version 4.0 or greater is required.}.

Up to XEmacs 21.2-b32 all configuration choices are passed on to
@code{nmake} as command-line options.

XEmacs versions > 21.2-b32
support @file{nt/config.inc} which is generated according to user
choices made under

@example
[Browse Build Make ...]
@end example

by

@example
[Generate config.inc]
@end example

which you have to save after reviewing it shortly.

@node Generate XEmacs Build Report, Known Problems of Build, Build XEmacs With Microsoft Tools, Top
@comment node-name,    next,  previous,      up
@chapter Generate XEmacs Build Report

This is a GUI making use of the @code{build-report} feature provided
with XEmacs.

When used standalone, you have to first

@example
[Browse Build Report ...]
@end example

to pick up the information for the XEmacs build you would like to
generate the report for.

@c #### If you use @code{build-report} as part of the @code{build} package, you should not save any customized @code{build-report} variables, so that @code{build} can ???

@node Known Problems of Build, Concept Index, Generate XEmacs Build Report, Top
@chapter Known Problems of Build
@cindex Limitations
@cindex Bugs

@enumerate

@item
Activated buttons appear to be inactive.

@itemize @bullet

@item
Problem

The buttons
@example
[Build XEmacs From CVS Now]
@end example
and
@example
[Build XEmacs From Tarballs Now]
@end example
don't show as active after being re-activated due to a bug in
wid-edit.el in XEmacs 21.1.12 and below.

@item
Workaround

You can easily find which button is active by using
@kbd{TAB} runs `widget-forward'
or
@kbd{Sh-TAB} runs `widget-backward'.

@item
Fix

@uref{http://www.xemacs.org/list-archives/xemacs-patches/200010/msg00031.html}
should fix this problem for later versions of XEmacs.

@end itemize

@item
Inactive buttons appear to be active.

@itemize @bullet

@item
Problem

XEmacs 21.2-b36 and below have another bug which will not render the
de-activated button as such.

@item
Workaround

You can easily find which button is active by using
@kbd{TAB} runs `widget-forward'
or
@kbd{Sh-TAB} runs `widget-backward'.

@item
Fix

None as of 2000-10-21.  See
@uref{http://www.xemacs.org/list-archives/xemacs-beta/200010/msg00194.html}.

@end itemize

@end enumerate

@node Concept Index, , Known Problems of Build, Top
@comment node-name,    next,  previous,      up
@unnumbered Concept Index
@printindex cp
@contents
@bye