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