======================================================================
                   Yash Build and Installation Guide
======================================================================

A one-liner for experts:
  ./configure && make && sudo make install

----------------------------------------------------------------------

Contents:
  1. What you need to build yash
  2. Configuration
  3. Building and testing
  4. Installation and uninstallation
  5. More configuration options

----------------------------------------------------------------------

1. What You Need to Build Yash

Yash is a program written in C99 (ISO/IEC 9899:1999), an extended
version of the C programming language, so you need a C99 compiler to
build it. If you do not have a C99 compiler installed on your system,
install one first. If you have a C99 compiler installed as the `c99'
command, it will suffice. Or if you have a recent version of the `gcc'
command installed from the GNU Compiler Collection, it will also do.
If you have a C99 compiler other than the `c99' or `gcc' command and
want to use that, you have to specify the compiler in configuration.

The build process of yash is automated using the `make' command, so
you need the `make' command installed in addition to the compiler. It
is recommended to use a version of `make' that conforms to POSIX. GNU
Make is confirmed to work, and most of other versions will also do.

Yash is based on API specified in the POSIX standard (IEEE Std
1003.1, 2008 Edition). If your system does not support the POSIX API,
yash may not be able to be built or work as expected.

Yash uses the `gettext' function to support localized messages. On
recent versions of GNU/Linux and Solaris, the `gettext' function is
provided in the standard C library, so you do not need any extra
library. On some other systems, the `gettext' function is provided in
an extra library called `libintl'. If you do not have the `libintl'
library installed on your system, first install the library or
disable the internationalization support in configuration to build
yash without it.

Yash uses the `curses' library to support powerful command line
editing. If you do not have the `curses' library installed on your
system, first install it or disable command line editing in
configuration to build yash without it.

----------------------------------------------------------------------

2. Configuration

The configuration process produces some files that are used in the
main build process. There files contain specific information about
which features are supported on your system, where yash will be
installed, etc.

The configuration is done by the shell script named `configure'. To
start the configuration, change the working directory of your shell to
the directory containing the `configure' script using the `cd' command
and invoke `sh configure'.

You can specify some options and/or variables when invoking the
`configure' script in order to specify:
  * the compiler, the archiver, etc. that are used in the build
  * features that will be supported by the resultant executable
  * directories where executable and other files are installed.
For example, to configure with the command line editing feature
disabled, invoke the script as `sh configure --disable-lineedit'.
To use the `cc' command as the compiler during the build,
`sh configure CC=cc'

The rest of this section describes the options and variables that can
be specified.

The following options can be specified to enable or disable specific
features of yash. By default, yash is built with all features enabled.

  --enable-array  --disable-array
    If disabled, the `array' built-in command is not available. Note
    that array variables are available regardless of this option.
  --enable-dirstack  --disable-dirstack
    If disabled, the `dirs', `pushd', and `popd' built-in commands are
    not available.
  --enable-double-bracket  --disable-double-bracket
    If disabled, the double-bracket command (the [[ ... ]] syntax) is
    not available. When this feature is enabled, the `test' built-in
    must also be enabled.
  --enable-help  --disable-help
    If disabled, the `help' built-in command is not available.
  --enable-history  --disable-history
    If disabled, the `fc' and `history' built-in commands are not
    available.
  --enable-lineedit  --disable-lineedit
    If disabled, command line editing for the interactive shell is
    not available. When this feature is enabled, the history feature
    must also be enabled.
  --enable-printf  --disable-printf
    If disabled, the `printf' and `echo' built-in commands are not
    available.
  --enable-socket  --disable-socket
    If disabled, socket redirection is not available. To enable this
    feature, your system have to support sockets.
  --enable-test  --disable-test
    If disabled, the `test' and `[' built-in commands are not
    available.
  --enable-ulimit  --disable-ulimit
    If disabled, the `ulimit' built-in command is not available. To
    enable this feature, your system must support the `getrlimit' and
    `setrlimit' functions in the standard C library.

The following option specifies the behavior of yash:

  --default-loadpath=...
    When yash is invoked, the $YASH_LOADPATH variable is initialized
    to this value.
    (default: <datadir>/yash)

The following options specify where files are installed:

  --prefix=...
    The basic installation path prefix.
    (default: /usr/local)
  --exec-prefix=...
    The basic installation path prefix for binaries.
    (default: <prefix>)
  --bindir=...
    The directory where the main executable binary is installed.
    (default: <exec-prefix>/bin)
  --datarootdir=...
    The basic installation path prefix for files other than the main
    executable binary.
    (default: <prefix>/share)
  --datadir=...
    The directory where auxiliary script files are installed.
    (default: <datarootdir>)
  --localedir=...
    The directory where localized message data are installed.
    (default: <datarootdir>/locale)
  --mandir=...
    The directory where roff-format manual pages are installed.
    (default: <datarootdir>/man)
  --docdir=...
    The directory where non-roff-format manual pages are installed.
    (default: <datarootdir>/doc/yash)
  --htmldir=...
    The directory where HTML manual pages are installed.
    (default: <docdir>)

The following variables can be used to specify commands and their
options used during the build:

  CC=...
    This specifies the compiler/linker command used during the build.
  CFLAGS=...
    This specifies the compiler option used in compiling (but not in
    linking). This overrides the options used in the default
    configuration.
  CADDS=...
    This specifies the compiler option used in compiling (but not in
    linking) in addition to the CFLAGS variable above. You can use
    CADDS to add compiler options to the default ones.
  LDFLAGS=...
    This specifies the linker option used in linking (but not in
    compiling). This overrides the options used in the default
    configuration. This variable does not include options that specify
    linked libraries (see LDLIBS below).
  LDADDS=...
    This specifies the linker option used in linking (but not in
    compiling) in addition to the LDFLAGS variable above. You can use
    LDADDS to add linker options to the default ones.
  LDLIBS=...
    This specifies the linker option that specify libraries linked to
    the executable binary. This overrides the options automatically
    detected by the configuration process.
  AR=...
    This specifies the archiver command used during the build.
  ARFLAGS=...
    This specifies the archiver option used in making a binary
    archive. This overrides the options used in the default
    configuration.
  LINGUAS=...
    This specifies the names of locales for which localized message
    data are installed. To specify more than one locale, separate
    names by spaces. (All space-separated names must be given at once
    in one variable value. The whole variable value should be properly
    quoted when invoking the `configure' script.)
  INSTALL=...
    This specifies the installer command used in installation.

----------------------------------------------------------------------

3. Building and Testing

Once the configuration is done, to build yash, invoke the `make'
command from your shell. The `make' command will automatically invoke
the compiler and linker in a proper order to produce the executable
binary of yash.

After yash is built, you can test the functionality of it by invoking
`make test'. (Actually, you can directly invoke `make test' before
`make' because the test process automatically builds yash if it is not
yet built.)

----------------------------------------------------------------------

4. Installation and Uninstallation

After yash is built, to install yash in your system, invoke
`make install'. This will install the main executable binary of yash
and all auxiliary files used by yash. If the installation directories
are not specified in the configuration, the files are installed into
the following directories by default:

  Main executable binary:   /usr/local/bin
  Auxiliary shell scripts:  /usr/local/share/yash
  Localization data:        /usr/local/share/locale
  Roff-format manual:       /usr/local/share/man
  HTML-format manual:       /usr/local/share/doc/yash

In most systems, a special permission is required to install files
into these directories. Use the `sudo' or other proper command to
obtain the permission or you may want to install into other
directories by specifying the directories in the configuration.

Instead of `make install', you can use `make install-binary' to
install the main binary only or `make install-data' to install the
other data files only.

Instead of `make install' or `make install-binary', you can use
`make install-strip' or `make install-binary-strip', respectively, to
remove debugging information from the binary during installation. This
makes the installed binary size smaller.

To uninstall yash, invoke `make uninstall'. You can instead use
`make uninstall-binary' or `make uninstall-data' to uninstall the main
binary or the other data files only, respectively.

----------------------------------------------------------------------

5. More Configuration Options

After invoking the `configure' script, you can manually edit the
`config.h' file to customize yash more. These options cannot be
configured by the `configure' script because they are not so
interesting for most people to customize.

The options can be set by defining macros in the `config.h' file as
described below. Some of the options are Boolean options. To enable a
Boolean option, define the corresponding macro as a non-zero integer
value. To disable a Boolean option, define the macro as zero or leave
it undefined. For non-Boolean options, the default value is shown to
the right of the macro name.

#define ALIAS_LIST_MAX 30
This macro must be defined as a positive integer.
This macro specifies the maximum number of aliases that can be
expanded recursively.

#define DOUBLE_DIVISION_BY_ZERO_ERROR 1  /* Boolean option */
If this macro is set to a non-zero, division by zero in floating-point
arithmetic is treated as an error. Otherwise, division by zero is
assumed to return a valid result (like infinity).

#define FG_DONT_SAVE_TERMINAL 1  /* Boolean option */
When a program that changes the terminal settings is invoked in the
background and later continued in the foreground by the `fg' built-in
command, it may leave the terminal in the wrong settings. By default,
the `fg' command works around this problem by saving the terminal
settings before continuing the program and restoring the settings
after the program has finished. Defining this macro as a non-zero
disables this workaround.

#define FIXED_SIGNAL_AS_ERROR 1  /* Boolean option */
As specified in the POSIX standard, if signal handlers that ignore
signals are inherited from the invoker process to a shell process, the
signal handlers cannot be removed by the `trap' built-in command if
the shell is non-interactive. This macro specifies the behavior of the
`trap' command in such a case. If this macro is set to a non-zero, the
command results in an error. Otherwise, the command returns the exit
status of success without any error message. Note that the signal
handlers are not removed regardless of this macro.

#define FORMAT_INDENT_WIDTH 3
This macro must be defined as a non-negative integer.
This macro specifies the number of spaces used to indent commands that
are formated and printed by the shell.

#define MAX_HISTSIZE 1000000
This macro specifies the maximum size of history.
The value must not over (INT_MAX / 10).

#define HISTORY_MIN_MAX_NUMBER 100000
This macro specifies the number of history entry at which the number
wraps back to 1. (If there are very many history entries, the entry
number may wrap at a number larger than this value.)
The value must be a power of 10 that is not less than 32768.

#define DEFAULT_HISTSIZE 500
This macro specifies the default history size.
The value must be 128 or larger.

#define LIST_AMBIGUOUS_OPTIONS 1  /* Boolean option */
When an option specified in invocation of the shell or a built-in
command is ambiguous, a list of option names that match the specified
ambiguous name is printed if this macro is defined as a non-zero.

#define MAX_PREDICTION_SAMPLE 10000
This macro must be defined as a non-negative integer.
This macro specifies the maximum number of history entries that are
considered in computing a command line prediction candidate.

#define SHELLFDMINMAX 100
This macro must be defined as an integer that is not less than 10.
When the shell opens a file that is not directly used by user
commands, the file descriptor for the file is chosen from integers
that is not less than the value of this macro.

#define YASH_DISABLE_SUPERUSER 1  /* Boolean option */
If this macro is set to a non-zero, the user whose user ID is zero is
not treated as a superuser, who is considered to have special
privilege about file access.