install-texi.in

早期freebsd实现

procedure.  However, for the long term, it is usually not a good idea to
leave directories world-writable (especially directories where
executables come from).

For better security, remove public write access from
@file{||INSTALLdir||/cygnus} and @file{@var{shr}/cygnus}.  See your
System Administrator for the correct permissions at your site.
@end enumerate

You're done!  Anyone who puts @samp{||INSTALLdir||/||RELEASEDIR||/bin} in
her or his @code{PATH} can use the Developer's Kit.

@node Examples, Install-Options, Installing, Top
@unnumbered Installation Examples

Once you've extracted @code{Install} from your tape,
you can tell @code{Install} what software to install, what form of the
programs you need, and what installation steps to do.  Here are some
examples covering common situations.  For a full explanation of each
possible @code{Install} argument, @pxref{Install-Options,,Installation
Options}.

@code{Install}'s default tape drive is @code{||DEVdflt||}, which is
right for the most common cases (||TAPEdflt|| tapes, read on ||HOST||
systems).  If your tape drive is different, you need to use the
@samp{-tape=/dev/@var{tape}} option; the examples show this option
for completeness.  Remember to specify a @emph{non-rewinding} tape
device.

@menu
* binaries::                    Installing binaries only
* ||HOSTstr||-remote::          Reading tape on any machine, finishing on ||HOST||
* source-remove::               Removing Source
@end menu

@node binaries, ||HOSTstr||-remote, Examples, Examples
@unnumberedsubsec Installing binaries only
@ignore
@c ignore til UPDATE fulfilled for all hosts.
For this example, we assume you've got the release on an Exabyte tape,
and that your ||HOST|| reads Exabytes with 
@samp{/dev/nrst1}.
@c UPDATE! exabyes on non-Sun hosts?
@end ignore

@cartouche
@example
@c eg$ @b{./Install -tape=/dev/nrst1 bin}
eg$ @b{./Install -tape=/dev/@var{tape} bin}
@end example
@end cartouche

If you don't want the source---for instance, to save space---you can use
the argument @samp{bin}.

@node ||HOSTstr||-remote, source-remove, binaries, Examples
@unnumberedsubsec Reading tape on any machine, finishing on ||HOST||

@cartouche
@example
@emph{On a machine on your network with a tape drive:}
eg-tp$ @b{./Install -tape=/dev/@var{tape} -installdir=@var{shr}/cygnus extract}

@emph{On your ||HOST||}
eg$ @b{ln -s @var{shr}/cygnus ||INSTALLdir||/cygnus}
eg$ @b{cd ||INSTALLdir||/cygnus/||RELEASEDIR||-||RELNO||}

@i{Native configurations only:}
eg$ @b{./Install @b{f}ixincludes test}
@end example
@end cartouche

@noindent
If your ||HOST|| doesn't have a tape drive, but another machine that can
mount some shared directory @var{shr} does have one, you can carry out
the first step of the installation from the machine with a tape drive,
as shown.  Note that you have to say @samp{extract} on the
@code{Install} command line.  This alerts @code{Install} to stop the
install procedure after it reads the tape.  You still have to finish the
installation, but the last two steps have to run on your ||HOST||.  (If
you forget, there's no great harm done: @code{Install} will notice that
it can't carry out a full installation on the wrong machine, and will
stop with an error message---then you can go back and try again.  When
@code{Install} notices a problem like this, it doesn't carry out
@emph{any} action other than giving a helpful error message).

Unless you are installing a cross-development tape (the tape label says
@samp{target=@var{machine}} for cross configurations), 
the @samp{fixincludes} part of the installation is essential.  Please
see the full explanation (@pxref{Why-fixincludes,,Why Convert System
Header Files?}), if you're curious.

@node source-remove,  , ||HOSTstr||-remote, Examples
@unnumberedsubsec Removing Source
The @code{Install} script can remove anything it can install.  For
example, if after installing the complete Developer's Kit on your
machine you decide to remove the source files:

@cartouche
@example
eg$ @b{cd ||INSTALLdir||/cygnus/||RELEASEDIR||-||RELNO||}
eg$ @b{./Install remove source}
@end example
@end cartouche

@noindent
In general, to remove a part of the Developer's Kit, use the same
@code{Install} command line that would extract that part, but add the
keyword @code{remove}.  The @code{-tape} option is not necessary for
removing.

@node Install-Options, Links, Examples, Top
@unnumbered Installation Options

There are two kinds of command-line arguments to @code{Install}, which
you can use to direct its operation:
@itemize @bullet
@item
@emph{What form of the programs} to install.  You can choose among ||HOST||
binaries (argument @code{bin}) and source code (@code{source}).
If you don't specify either of these, @code{Install} assumes you want
both source, and binaries for ||HOST||.

@item
@emph{What installation actions} to carry out.  A full installation
involves up to three steps, and @code{Install} has options to let you
choose them explicitly.  The steps are
@enumerate
@item
extracting source from the tape (option
@code{extract})
@item
writing copies of your system include files adjusted for portability (needed
for the compilation tools; option @code{fixincludes})
@item
running a simple test of the installed programs
(option @code{test})
@end enumerate

The last two of these actions (@code{fixincludes} and
@code{test}) are @emph{not needed for cross-development} configurations.
(A cross-development configuration runs on a ||HOST||, but is meant to
develop code for another platform.  Cross development
tapes have @samp{target=@var{machine}} on the Cygnus tape label.)

These two actions can only run on your ||HOST||.  If you read the
tape on another machine, you must specify the @code{extract} option
explicitly, to indicate that you don't expect the other two actions to
run (and are aware of the need to run further installation steps on your
||HOST||).
@end itemize

@code{Install} also has two command line options: @samp{-tape}
and @w{@samp{-installdir}}.  You can use these to adapt the
installation to your system.

Here is a summary of all of @code{Install}'s command-line options,
followed by a more detailed explanation of each:

@example
Install @r{[} -tape=/dev/@var{tape} @r{]}
       @r{[} -installdir=@var{directory} @r{]}
       @r{[} bin @r{]} @r{[} source @r{]}
       @r{[} extract @r{]} @r{[} fixincludes @r{]} @r{[} test @r{]}
       @r{[} remove @r{]}
@end example

@table @code
@item -tape=/dev/@var{tape}
@itemx -tape=@var{tarfile}
Specify the @emph{non-rewinding} device name for your tape drive as
@var{tape}.

If you extract the installation script and tarfile on some other system,
and transfer them to your ||HOST|| for installation, use use the name of
the tarfile instead of a device name with @samp{-tape}.  @xref{No
Drive,,No Local Tape Drive}, for more discussion.

@item -installdir=@var{directory}
If you have no write access to @samp{||INSTALLdir||/cygnus} or @samp{||INSTALLdir||}, use
this option to specify an alternate @var{directory} for placing your
software---but beware: the software is configured to go in
@samp{||INSTALLdir||/cygnus}, and you'll have to override or change that too.
@xref{Paths,,Changing the Paths}.

@item bin
@itemx source
By default, @code{Install} extracts both source, and binaries for your
||HOST||.  Instead of relying on the default, you 
can use these options to say exactly what forms you
want.  You need to do this if
@itemize @bullet
@item 
you want only binaries, or
@item
you want only source.
@end itemize

@noindent
@code{Install} is designed to share files, wherever
possible, between installations for different hosts (of the same
release).  If you get Cygnus release tapes configured for different
hosts, there is no need to do a binary-only install of some of the
tapes to save space on a shared file system; @code{Install} arranges the
files so that all hosts will share the same source
files.  Documentation files are shared as well.
See @ref{Links,,Links for Easy Access and Updating}, for a
discussion of how to manage the directory structure used for this
purpose. 

@item extract
@item fixincludes
@item test
On a ``cross-development'' configuration, only the @samp{extract} step
is used.

On a ``native'' configuration---meant for developing ||HOST||
software---a full installation includes up to three things: (1)
extracting software from the tape; (2) creating @sc{ansi}-C conforming
copies of your system's standard header files; and (3) testing the
installation.  You can execute these steps separately by specifying
@samp{extract}, @samp{fixincludes}, or @samp{test} on the @code{Install}
command line.

On the native configuration, after you run @samp{extract},
@samp{fixincludes} is essential to use the compiler.  @samp{fixincludes}
@emph{does not change your system's original header files;}
@code{Install} writes the converted copies in a separate,
@sc{gcc}-specific directory.  @xref{Why-fixincludes,,Why Convert System
Header Files?}, for more discussion of the @samp{fixincludes} step.
@code{Install} will only attempt these last two steps if you run it on
the ||HOST||.

@samp{test} (used only for the native configuration) is a confidence-building
step, and doesn't actually change the state of the installed software.
The @samp{test} step may not make sense, depending on what other options
you've specified---if you install only source, there's nothing to test.

If you specify a step that doesn't make sense, @code{Install} will
notice the error, and exit (before doing anything at all) with an error
message, so you can try again.

When you run @samp{extract}, @code{Install} leaves a log file
@file{tar.log} in the installation directory---by default, in
@file{||INSTALLdir||/cygnus}.  When you run @samp{fixincludes},
@code{Install} leaves a log file @file{fixincludes.log} in the
@file{||RELEASEDIR||-||RELNO||} subdirectory.

@item remove
You can also use @code{Install} to remove parts of the release after
you've installed them.  Identify what to remove with either of the
command-line options @samp{source} or @samp{bin}; if you specify
@samp{remove} as well, @code{Install} will try to erase parts of the
installation from your system.  @xref{Removing,,Removing Parts of the Developer's
Kit}, for an example.
@end table

@menu
* Why-fixincludes::             Why Convert System Header Files?
@end menu

@node Why-fixincludes,  , Install-Options, Install-Options
@unnumberedsec Why Convert System Header Files?

@quotation
The @samp{fixincludes} installation step described here @emph{applies
only to the ``native'' configuration} of the Developer's Kit---that is,
only if your tape is configured to develop software for a ||HOST||.
If you have a ``cross-development'' tape, configured to develop software
for another machine, the system header files from your ||HOST|| are not
needed for the GNU compilers.  Cross-development tapes have
@samp{target=@var{machine}} on the Cygnus tape label.
@end quotation

@c UPDATE! Is this really needed on @emph{all} hosts?
@c FIXME!  is non-Solaris text really good for all other natives?
For the native configuration, it is very important to run @samp{Install
fixincludes} (on @emph{each host} where you install the compiler
binaries).

@ifclear HOSTsolaris2
When the @sc{ansi x3j11} committee finished developing a standard for
the C language, a few things that had worked one way in many traditional
C compilers ended up working differently in @sc{ansi} C.  Most of these
changes are improvements.  But some Unix header files still rely on the
old C meanings, in cases where the Unix vendor has not yet converted to
using an @sc{ansi} C compiler for the operating system itself.
@samp{Install fixincludes} does a mechanical translation that writes
@sc{ansi} C versions of some system header files into a new,
@sc{gcc}-specific include directory---@emph{your system's original
header files are not affected.}
@end ifclear

@ifset HOSTsolaris2
The C header files supplied with SVr4 versions of Unix depend on a
questionable interpretation of the @sc{ansi} C standard: they test for a
non-@sc{ansi} environment by checking whether @code{__STDC__} is defined
as zero.  The @sc{ansi} standard actually only specifies that
@code{__STDC__} will be defined to 1; if it is defined to any other
value, the environment is not @sc{ansi} C compatible, and @sc{ansi} C
says nothing about what that value might be.

@sc{gcc} defines @code{__STDC__} to 1 when running with @samp{-ansi},
when it functions as an ``@sc{ansi} C superset'' compiler.  (It also sets
@code{__STRICT_ANSI__} when it runs with the @samp{-pedantic} option.)
However, @sc{gcc} leaves @code{__STDC__} undefined when it is not
running as an @sc{ansi} C compiler.

Unfortunately, the Solaris 2 header files follow the SVr4 choice.  Since
@sc{gcc} never defines @code{__STDC__} as 0, the distributed header
files can leave out some declarations.  (Look in @file{/usr/include/time.h},
for example.)
@end ifset

@samp{Install fixincludes} makes copies of the system include files,
which have these nonstandard features removed so that @sc{gcc} can
process them.  These copies are placed in a new, @sc{gcc}-specific
include directory---@emph{your system's original header files are not
affected.} Once these fixed header files are created, @sc{gcc} finds and
uses them automatically.

If you don't run @code{fixincludes}, the GNU C compiler can only use the
original system header files when you compile new C programs.  @emph{In
some cases, the resulting programs will fail at run-time}.

@node Links, Running, Install-Options, Top
@unnumbered Links for Easy Access and Updating
Once you've extracted them from the tape, the tools are installed under
a directory named @file{||RELEASEDIR||-||RELNO||}.  We put the release
number in the directory name so that you can
keep several releases installed at the same time, if you wish.  In order
to simplify administrative procedures (such as upgrades to future Cygnus
Progressive releases), we recommend that you establish a symbolic link
@file{||INSTALLdir||/cygnus/||RELEASEDIR||} to this directory.  For example, assuming
you've used the default installation path:

@cartouche
@example
eg$ @b{cd ||INSTALLdir||/cygnus}
eg$ @b{ln -s ||RELEASEDIR||-||RELNO|| ||RELEASEDIR||}
@end example
@end cartouche

Directories of host-independent files (source and documentation) are
installed directly under @file{||RELEASEDIR||-||RELNO||}.  However, to
accomodate binaries for multiple hosts in a single directory structure,
the binary files for your ||HOST|| are in a subdirectory
@file{H-||HOSTstr||}. 

This means that one more level of symbolic links is helpful, to allow
your users to keep the same execution path defined even if they
sometimes use ||HOST|| binaries and sometimes binaries for another
machine.  Even if this doesn't apply now, you might want it in the
future; establishing these links now can save your users the trouble of
changing all their paths later.  The idea is to build
@samp{||INSTALLdir||/||RELEASEDIR||/bin} on each machine so that it points to the
appropriate binary subdirectory for each machine---for instance,
@samp{||INSTALLdir||/cygnus/||RELEASEDIR||/H-||HOSTstr||}.

You may need to use @code{su} again briefly to establish these links:

@cartouche
@example
eg$ @b{ln -s ||INSTALLdir||/cygnus/||RELEASEDIR||/H-||HOSTstr|| ||INSTALLdir||/||RELEASEDIR||}
@end example
@end cartouche