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, so 'sudo make install' might be
  28      required.  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 'purify'.  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 an
 244      older version originally derived from the 4.2 BSD 'malloc'.  This
 245      'malloc' is very fast, but wastes some space on each allocation.
 246      This option is enabled by default.  The 'NOTES' file contains a
 247      list of systems for which this should be turned off, and
 248      'configure' disables this option automatically for a number of
 249      systems.
 250
 251 '--with-curses'
 252      Use the curses library instead of the termcap library.  This should
 253      be supplied if your system has an inadequate or incomplete termcap
 254      database.
 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').
 272
 273 '--with-libintl-prefix[=PREFIX]'
 274      Define this to make Bash link with a locally-installed version of
 275      the libintl library instead of the version in 'lib/intl'.
 276
 277 '--with-libiconv-prefix[=PREFIX]'
 278      Define this to make Bash look for libiconv in PREFIX instead of the
 279      standard system locations.  There is no version included with Bash.
 280
 281 '--enable-minimal-config'
 282      This produces a shell with minimal features, close to the
 283      historical Bourne shell.
 284
 285 There are several '--enable-' options that alter how Bash is compiled,
 286 linked, and installed, rather than changing run-time features.
 287
 288 '--enable-largefile'
 289      Enable support for large files
 290      (http://www.unix.org/version2/whatsnew/lfs20mar.html) if the
 291      operating system requires special compiler options to build
 292      programs which can access large files.  This is enabled by default,
 293      if the operating system provides large file support.
 294
 295 '--enable-profiling'
 296      This builds a Bash binary that produces profiling information to be
 297      processed by 'gprof' each time it is executed.
 298
 299 '--enable-separate-helpfiles'
 300      Use external files for the documentation displayed by the 'help'
 301      builtin instead of storing the text internally.
 302
 303 '--enable-static-link'
 304      This causes Bash to be linked statically, if 'gcc' is being used.
 305      This could be used to build a version to use as root's shell.
 306
 307 The 'minimal-config' option can be used to disable all of the following
 308 options, but it is processed first, so individual options may be enabled
 309 using 'enable-FEATURE'.
 310
 311 All of the following options except for 'alt-array-implementation',
 312 'disabled-builtins', 'direxpand-default', 'strict-posix-default', and
 313 'xpg-echo-default' are enabled by default, unless the operating system
 314 does not provide the necessary support.
 315
 316 '--enable-alias'
 317      Allow alias expansion and include the 'alias' and 'unalias'
 318      builtins (*note Aliases::).
 319
 320 '--enable-alt-array-implementation'
 321      This builds bash using an alternate implementation of arrays (*note
 322      Arrays::) that provides faster access at the expense of using more
 323      memory (sometimes many times more, depending on how sparse an array
 324      is).
 325
 326 '--enable-arith-for-command'
 327      Include support for the alternate form of the 'for' command that
 328      behaves like the C language 'for' statement (*note Looping
 329      Constructs::).
 330
 331 '--enable-array-variables'
 332      Include support for one-dimensional array shell variables (*note
 333      Arrays::).
 334
 335 '--enable-bang-history'
 336      Include support for 'csh'-like history substitution (*note History
 337      Interaction::).
 338
 339 '--enable-brace-expansion'
 340      Include 'csh'-like brace expansion ( 'b{a,b}c' ==> 'bac bbc' ).
 341      See *note Brace Expansion::, for a complete description.
 342
 343 '--enable-casemod-attributes'
 344      Include support for case-modifying attributes in the 'declare'
 345      builtin and assignment statements.  Variables with the 'uppercase'
 346      attribute, for example, will have their values converted to
 347      uppercase upon assignment.
 348
 349 '--enable-casemod-expansion'
 350      Include support for case-modifying word expansions.
 351
 352 '--enable-command-timing'
 353      Include support for recognizing 'time' as a reserved word and for
 354      displaying timing statistics for the pipeline following 'time'
 355      (*note Pipelines::).  This allows pipelines as well as shell
 356      builtins and functions to be timed.
 357
 358 '--enable-cond-command'
 359      Include support for the '[[' conditional command.  (*note
 360      Conditional Constructs::).
 361
 362 '--enable-cond-regexp'
 363      Include support for matching POSIX regular expressions using the
 364      '=~' binary operator in the '[[' conditional command.  (*note
 365      Conditional Constructs::).
 366
 367 '--enable-coprocesses'
 368      Include support for coprocesses and the 'coproc' reserved word
 369      (*note Pipelines::).
 370
 371 '--enable-debugger'
 372      Include support for the bash debugger (distributed separately).
 373
 374 '--enable-dev-fd-stat-broken'
 375      If calling 'stat' on /dev/fd/N returns different results than
 376      calling 'fstat' on file descriptor N, supply this option to enable
 377      a workaround.  This has implications for conditional commands that
 378      test file attributes.
 379
 380 '--enable-direxpand-default'
 381      Cause the 'direxpand' shell option (*note The Shopt Builtin::) to
 382      be enabled by default when the shell starts.  It is normally
 383      disabled by default.
 384
 385 '--enable-directory-stack'
 386      Include support for a 'csh'-like directory stack and the 'pushd',
 387      'popd', and 'dirs' builtins (*note The Directory Stack::).
 388
 389 '--enable-disabled-builtins'
 390      Allow builtin commands to be invoked via 'builtin xxx' even after
 391      'xxx' has been disabled using 'enable -n xxx'.  See *note Bash
 392      Builtins::, for details of the 'builtin' and 'enable' builtin
 393      commands.
 394
 395 '--enable-dparen-arithmetic'
 396      Include support for the '((...))' command (*note Conditional
 397      Constructs::).
 398
 399 '--enable-extended-glob'
 400      Include support for the extended pattern matching features
 401      described above under *note Pattern Matching::.
 402
 403 '--enable-extended-glob-default'
 404      Set the default value of the 'extglob' shell option described above
 405      under *note The Shopt Builtin:: to be enabled.
 406
 407 '--enable-function-import'
 408      Include support for importing function definitions exported by
 409      another instance of the shell from the environment.  This option is
 410      enabled by default.
 411
 412 '--enable-glob-asciirange-default'
 413      Set the default value of the 'globasciiranges' shell option
 414      described above under *note The Shopt Builtin:: to be enabled.
 415      This controls the behavior of character ranges when used in pattern
 416      matching bracket expressions.
 417
 418 '--enable-help-builtin'
 419      Include the 'help' builtin, which displays help on shell builtins
 420      and variables (*note Bash Builtins::).
 421
 422 '--enable-history'
 423      Include command history and the 'fc' and 'history' builtin commands
 424      (*note Bash History Facilities::).
 425
 426 '--enable-job-control'
 427      This enables the job control features (*note Job Control::), if the
 428      operating system supports them.
 429
 430 '--enable-multibyte'
 431      This enables support for multibyte characters if the operating
 432      system provides the necessary support.
 433
 434 '--enable-net-redirections'
 435      This enables the special handling of filenames of the form
 436      '/dev/tcp/HOST/PORT' and '/dev/udp/HOST/PORT' when used in
 437      redirections (*note Redirections::).
 438
 439 '--enable-process-substitution'
 440      This enables process substitution (*note Process Substitution::) if
 441      the operating system provides the necessary support.
 442
 443 '--enable-progcomp'
 444      Enable the programmable completion facilities (*note Programmable
 445      Completion::).  If Readline is not enabled, this option has no
 446      effect.
 447
 448 '--enable-prompt-string-decoding'
 449      Turn on the interpretation of a number of backslash-escaped
 450      characters in the '$PS0', '$PS1', '$PS2', and '$PS4' prompt
 451      strings.  See *note Controlling the Prompt::, for a complete list
 452      of prompt string escape sequences.
 453
 454 '--enable-readline'
 455      Include support for command-line editing and history with the Bash
 456      version of the Readline library (*note Command Line Editing::).
 457
 458 '--enable-restricted'
 459      Include support for a "restricted shell".  If this is enabled,
 460      Bash, when called as 'rbash', enters a restricted mode.  See *note
 461      The Restricted Shell::, for a description of restricted mode.
 462
 463 '--enable-select'
 464      Include the 'select' compound command, which allows the generation
 465      of simple menus (*note Conditional Constructs::).
 466
 467 '--enable-single-help-strings'
 468      Store the text displayed by the 'help' builtin as a single string
 469      for each help topic.  This aids in translating the text to
 470      different languages.  You may need to disable this if your compiler
 471      cannot handle very long string literals.
 472
 473 '--enable-strict-posix-default'
 474      Make Bash POSIX-conformant by default (*note Bash POSIX Mode::).
 475
 476 '--enable-translatable-strings'
 477      Enable support for '$"STRING"' translatable strings (*note Locale
 478      Translation::).
 479
 480 '--enable-usg-echo-default'
 481      A synonym for '--enable-xpg-echo-default'.
 482
 483 '--enable-xpg-echo-default'
 484      Make the 'echo' builtin expand backslash-escaped characters by
 485      default, without requiring the '-e' option.  This sets the default
 486      value of the 'xpg_echo' shell option to 'on', which makes the Bash
 487      'echo' behave more like the version specified in the Single Unix
 488      Specification, version 3.  *Note Bash Builtins::, for a description
 489      of the escape sequences that 'echo' recognizes.
 490
 491 The file 'config-top.h' contains C Preprocessor '#define' statements for
 492 options which are not settable from 'configure'.  Some of these are not
 493 meant to be changed; beware of the consequences if you do.  Read the
 494 comments associated with each definition for more information about its
 495 effect.