INSTALL

   1 Basic Installation
   2 ==================
   3
   4 These are installation instructions for Bash.
   5
   6 The simplest way to compile Bash is:
   7
   8   1. ‘cd’ to the directory containing the source code and type
   9      ‘./configure’ to configure Bash for your system.  If you're using
  10      ‘csh’ on an old version of System V, you might need to type ‘sh
  11      ./configure’ instead to prevent ‘csh’ from trying to execute
  12      ‘configure’ itself.
  13
  14      Running ‘configure’ takes some time.  While running, it prints
  15      messages telling which features it is checking for.
  16
  17   2. Type ‘make’ to compile Bash and build the ‘bashbug’ bug reporting
  18      script.
  19
  20   3. Optionally, type ‘make tests’ to run the Bash test suite.
  21
  22   4. Type ‘make install’ to install ‘bash’ and ‘bashbug’.  This will
  23      also install the manual pages and Info file, message translation
  24      files, some supplemental documentation, a number of example
  25      loadable builtin commands, and a set of header files for developing
  26      loadable builtins.  You may need additional privileges to install
  27      ‘bash’ to your desired destination, which may require ‘sudo make
  28      install’.  More information about controlling the locations where
  29      ‘bash’ and other files are installed is below (*note Installation
  30      Names::).
  31
  32 The ‘configure’ shell script attempts to guess correct values for
  33 various system-dependent variables used during compilation.  It uses
  34 those values to create a ‘Makefile’ in each directory of the package
  35 (the top directory, the ‘builtins’, ‘doc’, ‘po’, and ‘support’
  36 directories, each directory under ‘lib’, and several others).  It also
  37 creates a ‘config.h’ file containing system-dependent definitions.
  38 Finally, it creates a shell script named ‘config.status’ that you can
  39 run in the future to recreate the current configuration, a file
  40 ‘config.cache’ that saves the results of its tests to speed up
  41 reconfiguring, and a file ‘config.log’ containing compiler output
  42 (useful mainly for debugging ‘configure’).  If at some point
  43 ‘config.cache’ contains results you don't want to keep, you may remove
  44 or edit it.
  45
  46 To find out more about the options and arguments that the ‘configure’
  47 script understands, type
  48
  49      bash-4.2$ ./configure --help
  50
  51 at the Bash prompt in your Bash source directory.
  52
  53 If you want to build Bash in a directory separate from the source
  54 directory - to build for multiple architectures, for example - just use
  55 the full path to the configure script.  The following commands will
  56 build Bash in a directory under ‘/usr/local/build’ from the source code
  57 in ‘/usr/local/src/bash-4.4’:
  58
  59      mkdir /usr/local/build/bash-4.4
  60      cd /usr/local/build/bash-4.4
  61      bash /usr/local/src/bash-4.4/configure
  62      make
  63
  64 See *note Compiling For Multiple Architectures:: for more information
  65 about building in a directory separate from the source.
  66
  67 If you need to do unusual things to compile Bash, please try to figure
  68 out how ‘configure’ could check whether or not to do them, and mail
  69 diffs or instructions to <bash-maintainers@gnu.org> so they can be
  70 considered for the next release.
  71
  72 The file ‘configure.ac’ is used to create ‘configure’ by a program
  73 called Autoconf.  You only need ‘configure.ac’ if you want to change it
  74 or regenerate ‘configure’ using a newer version of Autoconf.  If you do
  75 this, make sure you are using Autoconf version 2.69 or newer.
  76
  77 You can remove the program binaries and object files from the source
  78 code directory by typing ‘make clean’.  To also remove the files that
  79 ‘configure’ created (so you can compile Bash for a different kind of
  80 computer), type ‘make distclean’.
  81
  82 Compilers and Options
  83 =====================
  84
  85 Some systems require unusual options for compilation or linking that the
  86 ‘configure’ script does not know about.  You can give ‘configure’
  87 initial values for variables by setting them in the environment.  Using
  88 a Bourne-compatible shell, you can do that on the command line like
  89 this:
  90
  91      CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
  92
  93 On systems that have the ‘env’ program, you can do it like this:
  94
  95      env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
  96
  97 The configuration process uses GCC to build Bash if it is available.
  98
  99 Compiling For Multiple Architectures
 100 ====================================
 101
 102 You can compile Bash for more than one kind of computer at the same
 103 time, by placing the object files for each architecture in their own
 104 directory.  To do this, you must use a version of ‘make’ that supports
 105 the ‘VPATH’ variable, such as GNU ‘make’.  ‘cd’ to the directory where
 106 you want the object files and executables to go and run the ‘configure’
 107 script from the source directory (*note Basic Installation::).  You may
 108 need to supply the ‘--srcdir=PATH’ argument to tell ‘configure’ where
 109 the source files are.  ‘configure’ automatically checks for the source
 110 code in the directory that ‘configure’ is in and in ‘..’.
 111
 112 If you have to use a ‘make’ that does not support the ‘VPATH’ variable,
 113 you can compile Bash for one architecture at a time in the source code
 114 directory.  After you have installed Bash for one architecture, use
 115 ‘make distclean’ before reconfiguring for another architecture.
 116
 117 Alternatively, if your system supports symbolic links, you can use the
 118 ‘support/mkclone’ script to create a build tree which has symbolic links
 119 back to each file in the source directory.  Here's an example that
 120 creates a build directory in the current directory from a source
 121 directory ‘/usr/gnu/src/bash-2.0’:
 122
 123      bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
 124
 125 The ‘mkclone’ script requires Bash, so you must have already built Bash
 126 for at least one architecture before you can create build directories
 127 for other architectures.
 128
 129 Installation Names
 130 ==================
 131
 132 By default, ‘make install’ will install into ‘/usr/local/bin’,
 133 ‘/usr/local/man’, etc.; that is, the “installation prefix” defaults to
 134 ‘/usr/local’.  You can specify an installation prefix other than
 135 ‘/usr/local’ by giving ‘configure’ the option ‘--prefix=PATH’, or by
 136 specifying a value for the ‘prefix’ ‘make’ variable when running ‘make
 137 install’ (e.g., ‘make install prefix=PATH’).  The ‘prefix’ variable
 138 provides a default for ‘exec_prefix’ and other variables used when
 139 installing Bash.
 140
 141 You can specify separate installation prefixes for architecture-specific
 142 files and architecture-independent files.  If you give ‘configure’ the
 143 option ‘--exec-prefix=PATH’, ‘make install’ will use PATH as the prefix
 144 for installing programs and libraries.  Documentation and other data
 145 files will still use the regular prefix.
 146
 147 If you would like to change the installation locations for a single run,
 148 you can specify these variables as arguments to ‘make’: ‘make install
 149 exec_prefix=/’ will install ‘bash’ and ‘bashbug’ into ‘/bin’ instead of
 150 the default ‘/usr/local/bin’.
 151
 152 If you want to see the files Bash will install and where it will install
 153 them without changing anything on your system, specify the variable
 154 ‘DESTDIR’ as an argument to ‘make’.  Its value should be the absolute
 155 directory path you'd like to use as the root of your sample installation
 156 tree.  For example,
 157
 158      mkdir /fs1/bash-install
 159      make install DESTDIR=/fs1/bash-install
 160
 161 will install ‘bash’ into ‘/fs1/bash-install/usr/local/bin/bash’, the
 162 documentation into directories within
 163 ‘/fs1/bash-install/usr/local/share’, the example loadable builtins into
 164 ‘/fs1/bash-install/usr/local/lib/bash’, and so on.  You can use the
 165 usual ‘exec_prefix’ and ‘prefix’ variables to alter the directory paths
 166 beneath the value of ‘DESTDIR’.
 167
 168 The GNU Makefile standards provide a more complete description of these
 169 variables and their effects.
 170
 171 Specifying the System Type
 172 ==========================
 173
 174 There may be some features ‘configure’ can not figure out automatically,
 175 but needs to determine by the type of host Bash will run on.  Usually
 176 ‘configure’ can figure that out, but if it prints a message saying it
 177 can not guess the host type, give it the ‘--host=TYPE’ option.  ‘TYPE’
 178 can either be a short name for the system type, such as ‘sun4’, or a
 179 canonical name with three fields: ‘CPU-COMPANY-SYSTEM’ (e.g.,
 180 ‘i386-unknown-freebsd4.2’).
 181
 182 See the file ‘support/config.sub’ for the possible values of each field.
 183
 184 Sharing Defaults
 185 ================
 186
 187 If you want to set default values for ‘configure’ scripts to share, you
 188 can create a site shell script called ‘config.site’ that gives default
 189 values for variables like ‘CC’, ‘cache_file’, and ‘prefix’.  ‘configure’
 190 looks for ‘PREFIX/share/config.site’ if it exists, then
 191 ‘PREFIX/etc/config.site’ if it exists.  Or, you can set the
 192 ‘CONFIG_SITE’ environment variable to the location of the site script.
 193 A warning: the Bash ‘configure’ looks for a site script, but not all
 194 ‘configure’ scripts do.
 195
 196 Operation Controls
 197 ==================
 198
 199 ‘configure’ recognizes the following options to control how it operates.
 200
 201 ‘--cache-file=FILE’
 202      Use and save the results of the tests in FILE instead of
 203      ‘./config.cache’.  Set FILE to ‘/dev/null’ to disable caching, for
 204      debugging ‘configure’.
 205
 206 ‘--help’
 207      Print a summary of the options to ‘configure’, and exit.
 208
 209 ‘--quiet’
 210 ‘--silent’
 211 ‘-q’
 212      Do not print messages saying which checks are being made.
 213
 214 ‘--srcdir=DIR’
 215      Look for the Bash source code in directory DIR.  Usually
 216      ‘configure’ can determine that directory automatically.
 217
 218 ‘--version’
 219      Print the version of Autoconf used to generate the ‘configure’
 220      script, and exit.
 221
 222 ‘configure’ also accepts some other, not widely used, boilerplate
 223 options.  ‘configure --help’ prints the complete list.
 224
 225 Optional Features
 226 =================
 227
 228 The Bash ‘configure’ has a number of ‘--enable-FEATURE’ options, where
 229 FEATURE indicates an optional part of Bash.  There are also several
 230 ‘--with-PACKAGE’ options, where PACKAGE is something like ‘bash-malloc’
 231 or ‘afs’.  To turn off the default use of a package, use
 232 ‘--without-PACKAGE’.  To configure Bash without a feature that is
 233 enabled by default, use ‘--disable-FEATURE’.
 234
 235 Here is a complete list of the ‘--enable-’ and ‘--with-’ options that
 236 the Bash ‘configure’ recognizes.
 237
 238 ‘--with-afs’
 239      Define if you are using the Andrew File System from Transarc.
 240
 241 ‘--with-bash-malloc’
 242      Use the Bash version of ‘malloc’ in the directory ‘lib/malloc’.
 243      This is not the same ‘malloc’ that appears in GNU libc, but a
 244      custom version originally derived from the 4.2 BSD ‘malloc’.  This
 245      ‘malloc’ is very fast, but wastes some space on each allocation,
 246      though it uses several techniques to minimize the waste.  This
 247      option is enabled by default.  The ‘NOTES’ file contains a list of
 248      systems for which this should be turned off, and ‘configure’
 249      disables this option automatically for a number of systems.
 250
 251 ‘--with-curses’
 252      Use the curses library instead of the termcap library.  ‘configure’
 253      usually chooses this automatically, since most systems include the
 254      termcap functions in the curses library.
 255
 256 ‘--with-gnu-malloc’
 257      A synonym for ‘--with-bash-malloc’.
 258
 259 ‘--with-installed-readline[=PREFIX]’
 260      Define this to make Bash link with a locally-installed version of
 261      Readline rather than the version in ‘lib/readline’.  This works
 262      only with Readline 5.0 and later versions.  If PREFIX is ‘yes’ or
 263      not supplied, ‘configure’ uses the values of the make variables
 264      ‘includedir’ and ‘libdir’, which are subdirectories of ‘prefix’ by
 265      default, to find the installed version of Readline if it is not in
 266      the standard system include and library directories.  If PREFIX is
 267      ‘no’, Bash links with the version in ‘lib/readline’.  If PREFIX is
 268      set to any other value, ‘configure’ treats it as a directory
 269      pathname and looks for the installed version of Readline in
 270      subdirectories of that directory (include files in PREFIX/‘include’
 271      and the library in PREFIX/‘lib’).  The Bash default is to link with
 272      a static library built in the ‘lib/readline’ subdirectory of the
 273      build directory.
 274
 275 ‘--with-libintl-prefix[=PREFIX]’
 276      Define this to make Bash link with a locally-installed version of
 277      the libintl library instead of the version in ‘lib/intl’.
 278
 279 ‘--with-libiconv-prefix[=PREFIX]’
 280      Define this to make Bash look for libiconv in PREFIX instead of the
 281      standard system locations.  The Bash distribution does not include
 282      this library.
 283
 284 ‘--enable-minimal-config’
 285      This produces a shell with minimal features, closer to the
 286      historical Bourne shell.
 287
 288 There are several ‘--enable-’ options that alter how Bash is compiled,
 289 linked, and installed, rather than changing run-time features.
 290
 291 ‘--enable-largefile’
 292      Enable support for large files
 293      (http://www.unix.org/version2/whatsnew/lfs20mar.html) if the
 294      operating system requires special compiler options to build
 295      programs which can access large files.  This is enabled by default,
 296      if the operating system provides large file support.
 297
 298 ‘--enable-profiling’
 299      This builds a Bash binary that produces profiling information to be
 300      processed by ‘gprof’ each time it is executed.
 301
 302 ‘--enable-separate-helpfiles’
 303      Use external files for the documentation displayed by the ‘help’
 304      builtin instead of storing the text internally.
 305
 306 ‘--enable-static-link’
 307      This causes Bash to be linked statically, if ‘gcc’ is being used.
 308      This could be used to build a version to use as root's shell.
 309
 310 The ‘minimal-config’ option can be used to disable all of the following
 311 options, but it is processed first, so individual options may be enabled
 312 using ‘enable-FEATURE’.
 313
 314 All of the following options except for ‘alt-array-implementation’,
 315 ‘disabled-builtins’, ‘direxpand-default’, ‘strict-posix-default’, and
 316 ‘xpg-echo-default’ are enabled by default, unless the operating system
 317 does not provide the necessary support.
 318
 319 ‘--enable-alias’
 320      Allow alias expansion and include the ‘alias’ and ‘unalias’
 321      builtins (*note Aliases::).
 322
 323 ‘--enable-alt-array-implementation’
 324      This builds Bash using an alternate implementation of arrays (*note
 325      Arrays::) that provides faster access at the expense of using more
 326      memory (sometimes many times more, depending on how sparse an array
 327      is).
 328
 329 ‘--enable-arith-for-command’
 330      Include support for the alternate form of the ‘for’ command that
 331      behaves like the C language ‘for’ statement (*note Looping
 332      Constructs::).
 333
 334 ‘--enable-array-variables’
 335      Include support for one-dimensional array shell variables (*note
 336      Arrays::).
 337
 338 ‘--enable-bang-history’
 339      Include support for ‘csh’-like history substitution (*note History
 340      Interaction::).
 341
 342 ‘--enable-bash-source-fullpath-default’
 343      Set the default value of the ‘bash_source_fullpath’ shell option
 344      described above under *note The Shopt Builtin:: to be enabled.
 345      This controls how filenames are assigned to the ‘BASH_SOURCE’ array
 346      variable.
 347
 348 ‘--enable-brace-expansion’
 349      Include ‘csh’-like brace expansion ( ‘b{a,b}c’ ↦ ‘bac bbc’ ).  See
 350      *note Brace Expansion::, for a complete description.
 351
 352 ‘--enable-casemod-attributes’
 353      Include support for case-modifying attributes in the ‘declare’
 354      builtin and assignment statements.  Variables with the ‘uppercase’
 355      attribute, for example, will have their values converted to
 356      uppercase upon assignment.
 357
 358 ‘--enable-casemod-expansion’
 359      Include support for case-modifying word expansions.
 360
 361 ‘--enable-command-timing’
 362      Include support for recognizing ‘time’ as a reserved word and for
 363      displaying timing statistics for the pipeline following ‘time’
 364      (*note Pipelines::).  This allows timing pipelines, shell compound
 365      commands, shell builtins, and shell functions, which an external
 366      command cannot do easily.
 367
 368 ‘--enable-cond-command’
 369      Include support for the ‘[[’ conditional command.  (*note
 370      Conditional Constructs::).
 371
 372 ‘--enable-cond-regexp’
 373      Include support for matching POSIX regular expressions using the
 374      ‘=~’ binary operator in the ‘[[’ conditional command.  (*note
 375      Conditional Constructs::).
 376
 377 ‘--enable-coprocesses’
 378      Include support for coprocesses and the ‘coproc’ reserved word
 379      (*note Pipelines::).
 380
 381 ‘--enable-debugger’
 382      Include support for the Bash debugger (distributed separately).
 383
 384 ‘--enable-dev-fd-stat-broken’
 385      If calling ‘stat’ on /dev/fd/N returns different results than
 386      calling ‘fstat’ on file descriptor N, supply this option to enable
 387      a workaround.  This has implications for conditional commands that
 388      test file attributes.
 389
 390 ‘--enable-direxpand-default’
 391      Cause the ‘direxpand’ shell option (*note The Shopt Builtin::) to
 392      be enabled by default when the shell starts.  It is normally
 393      disabled by default.
 394
 395 ‘--enable-directory-stack’
 396      Include support for a ‘csh’-like directory stack and the ‘pushd’,
 397      ‘popd’, and ‘dirs’ builtins (*note The Directory Stack::).
 398
 399 ‘--enable-disabled-builtins’
 400      Allow builtin commands to be invoked via ‘builtin xxx’ even after
 401      ‘xxx’ has been disabled using ‘enable -n xxx’.  See *note Bash
 402      Builtins::, for details of the ‘builtin’ and ‘enable’ builtin
 403      commands.
 404
 405 ‘--enable-dparen-arithmetic’
 406      Include support for the ‘((...))’ command (*note Conditional
 407      Constructs::).
 408
 409 ‘--enable-extended-glob’
 410      Include support for the extended pattern matching features
 411      described above under *note Pattern Matching::.
 412
 413 ‘--enable-extended-glob-default’
 414      Set the default value of the ‘extglob’ shell option described above
 415      under *note The Shopt Builtin:: to be enabled.
 416
 417 ‘--enable-function-import’
 418      Include support for importing function definitions exported by
 419      another instance of the shell from the environment.  This option is
 420      enabled by default.
 421
 422 ‘--enable-glob-asciiranges-default’
 423      Set the default value of the ‘globasciiranges’ shell option
 424      described above under *note The Shopt Builtin:: to be enabled.
 425      This controls the behavior of character ranges when used in pattern
 426      matching bracket expressions.
 427
 428 ‘--enable-help-builtin’
 429      Include the ‘help’ builtin, which displays help on shell builtins
 430      and variables (*note Bash Builtins::).
 431
 432 ‘--enable-history’
 433      Include command history and the ‘fc’ and ‘history’ builtin commands
 434      (*note Bash History Facilities::).
 435
 436 ‘--enable-job-control’
 437      This enables the job control features (*note Job Control::), if the
 438      operating system supports them.
 439
 440 ‘--enable-multibyte’
 441      This enables support for multibyte characters if the operating
 442      system provides the necessary support.
 443
 444 ‘--enable-net-redirections’
 445      This enables the special handling of filenames of the form
 446      ‘/dev/tcp/HOST/PORT’ and ‘/dev/udp/HOST/PORT’ when used in
 447      redirections (*note Redirections::).
 448
 449 ‘--enable-process-substitution’
 450      This enables process substitution (*note Process Substitution::) if
 451      the operating system provides the necessary support.
 452
 453 ‘--enable-progcomp’
 454      Enable the programmable completion facilities (*note Programmable
 455      Completion::).  If Readline is not enabled, this option has no
 456      effect.
 457
 458 ‘--enable-prompt-string-decoding’
 459      Turn on the interpretation of a number of backslash-escaped
 460      characters in the ‘$PS0’, ‘$PS1’, ‘$PS2’, and ‘$PS4’ prompt
 461      strings.  See *note Controlling the Prompt::, for a complete list
 462      of prompt string escape sequences.
 463
 464 ‘--enable-readline’
 465      Include support for command-line editing and history with the Bash
 466      version of the Readline library (*note Command Line Editing::).
 467
 468 ‘--enable-restricted’
 469      Include support for a “restricted shell”.  If this is enabled, Bash
 470      enters a restricted mode when called as ‘rbash’.  See *note The
 471      Restricted Shell::, for a description of restricted mode.
 472
 473 ‘--enable-select’
 474      Include the ‘select’ compound command, which allows generation of
 475      simple menus (*note Conditional Constructs::).
 476
 477 ‘--enable-single-help-strings’
 478      Store the text displayed by the ‘help’ builtin as a single string
 479      for each help topic.  This aids in translating the text to
 480      different languages.  You may need to disable this if your compiler
 481      cannot handle very long string literals.
 482
 483 ‘--enable-strict-posix-default’
 484      Make Bash POSIX-conformant by default (*note Bash POSIX Mode::).
 485
 486 ‘--enable-translatable-strings’
 487      Enable support for ‘$"STRING"’ translatable strings (*note Locale
 488      Translation::).
 489
 490 ‘--enable-usg-echo-default’
 491      A synonym for ‘--enable-xpg-echo-default’.
 492
 493 ‘--enable-xpg-echo-default’
 494      Make the ‘echo’ builtin expand backslash-escaped characters by
 495      default, without requiring the ‘-e’ option.  This sets the default
 496      value of the ‘xpg_echo’ shell option to ‘on’, which makes the Bash
 497      ‘echo’ behave more like the version specified in the Single Unix
 498      Specification, version 3.  *Note Bash Builtins::, for a description
 499      of the escape sequences that ‘echo’ recognizes.
 500
 501 The file ‘config-top.h’ contains C Preprocessor ‘#define’ statements for
 502 options which are not settable from ‘configure’.  Some of these are not
 503 meant to be changed; beware of the consequences if you do.  Read the
 504 comments associated with each definition for more information about its
 505 effect.