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