Update the build manual

signals
Gavin Howard 4 years ago
parent 3dd8ad88c5
commit 9425b9bfcd
Signed by untrusted user who does not match committer: gavin
GPG Key ID: C08038BDF280D33E
  1. 209
      manuals/build.md

@ -15,11 +15,12 @@ make
make install
```
To get all of the options, including any useful environment variables, use the
following command:
To get all of the options, including any useful environment variables, use
either one of the following commands:
```
./configure.sh -h
./configure.sh --help
```
To learn the available `make` targets run the following command after running
@ -56,8 +57,9 @@ make install
prioritized over `HOST_CFLAGS`. If neither are present, `HOSTCC` (or `HOST_CC`)
uses `CFLAGS` (see [Build Environment Variables][4] for more details).
It is expected that `CC` produces code for the target system. See
[Build Environment Variables][4] for more details.
It is expected that `CC` produces code for the target system and `HOSTCC`
produces code for the host system. See [Build Environment Variables][4] for more
details.
If an emulator is necessary to run the bootstrap binaries, it can be set with
the environment variable `GEN_EMU`.
@ -68,9 +70,10 @@ the environment variable `GEN_EMU`.
This `bc` supports `CC`, `HOSTCC`, `HOST_CC`, `CFLAGS`, `HOSTCFLAGS`,
`HOST_CFLAGS`, `CPPFLAGS`, `LDFLAGS`, `LDLIBS`, `PREFIX`, `DESTDIR`, `BINDIR`,
`DATAROOTDIR`, `DATADIR`, `MANDIR`, `MAN1DIR`, `LOCALEDIR` `EXECSUFFIX` and
`GEN_EMU` environment variables in `configure.sh`. Any values of those variables
given to `configure.sh` will be put into the generated Makefile.
`DATAROOTDIR`, `DATADIR`, `MANDIR`, `MAN1DIR`, `LOCALEDIR` `EXECSUFFIX`,
`EXECPREFIX` and `GEN_EMU` environment variables in `configure.sh`. Any values
of those variables given to `configure.sh` will be put into the generated
Makefile.
More detail on what those environment variables do can be found in the following
sections.
@ -126,6 +129,8 @@ Defaults to empty.
The prefix to install to.
Can be overridden by passing the `--prefix` option to `configure.sh`.
Defaults to `/usr/local`.
### `DESTDIR`
@ -133,30 +138,41 @@ Defaults to `/usr/local`.
Path to prepend onto `PREFIX`. This is mostly for distro and package
maintainers.
This can be passed either to `configure.sh` or `make install`. If it is passed
to both, the one given to `configure.sh` takes precedence.
Defaults to empty.
### `BINDIR`
The directory to install binaries in.
Can be overridden by passing the `--bindir` option to `configure.sh`.
Defaults to `$PREFIX/bin`.
### `DATAROOTDIR`
The root directory to install data files in.
Can be overridden by passing the `--datarootdir` option to `configure.sh`.
Defaults to `$PREFIX/share`.
### `DATADIR`
The directory to install data files in.
Can be overridden by passing the `--datadir` option to `configure.sh`.
Defaults to `$DATAROOTDIR`.
### `MANDIR`
The directory to install manpages in.
Can be overridden by passing the `--mandir` option to `configure.sh`.
Defaults to `$DATADIR/man`
### `MAN1DIR`
@ -164,12 +180,16 @@ Defaults to `$DATADIR/man`
The directory to install Section 1 manpages in. Because both `bc` and `dc` are
Section 1 commands, this is the only relevant section directory.
Can be overridden by passing the `--man1dir` option to `configure.sh`.
Defaults to `$MANDIR/man1`.
### `LOCALEDIR`
The directory to install locales in.
Can be overridden by passing the `--localedir` option to `configure.sh`.
Defaults to `$DATAROOTDIR/locale`.
### `EXECSUFFIX`
@ -180,6 +200,14 @@ want to replace the default `bc`.
Defaults to empty.
### `EXECPREFIX`
The prefix to append onto the executable names *when building and installing*.
This is for packagers and distro maintainers who want this `bc` as an option,
but do not want to replace the default `bc`.
Defaults to empty.
### `GEN_EMU`
The emulator to run bootstrap binaries under. This is only if the binaries
@ -196,17 +224,27 @@ This `bc` comes with several build options, all of which are enabled by default.
All options can be used with each other, with a few exceptions that will be
noted below.
**NOTE**: All long options with mandatory argumenst accept either one of the
following forms:
```
--option arg
--option=arg
```
### `bc` Only
To build `bc` only (no `dc`), use either one of the following commands for the
To build `bc` only (no `dc`), use any one of the following commands for the
configure step:
```
./configure.sh -b
./configure.sh --bc-only
./configure.sh -D
./configure.sh --disable-dc
```
Those two commands are equivalent.
Those commands are all equivalent.
***Warning***: It is an error to use those options if `bc` has also been
disabled (see below).
@ -218,10 +256,12 @@ configure step:
```
./configure.sh -d
./configure.sh --dc-only
./configure.sh -B
./configure.sh --disable-bc
```
Those two commands are equivalent.
Those commands are all equivalent.
***Warning***: It is an error to use those options if `dc` has also been
disabled (see above).
@ -230,22 +270,30 @@ disabled (see above).
### Signal Handling
To disable signal handling, use the `-S` flag in the configure step:
To disable signal handling, pass either the `-S` flag or the
`--disable-signal-handling` option to `configure.sh`, as follows:
```
./configure.sh -S
./configure.sh --disable-signal-handling
```
Both commands are equivalent.
<a name="build-history"/>
### History
To disable signal handling, use the `-H` flag in the configure step:
To disable signal handling, pass either the `-H` flag or the `--disable-history`
option to `configure.sh`, as follows:
```
./configure.sh -H
./configure.sh --disable-history
```
Both commands are equivalent.
History is automatically disabled when building for Windows or on another
platform that does not support the terminal handling that is required.
@ -255,14 +303,18 @@ should be to retry with history disabled.
### NLS (Locale Support)
To disable locale support (use only English), use the `-N` flag in the configure
step:
To disable locale support (use only English), pass either the `-N` flag or the
`--disable-nls` option to `configure.sh`, as follows:
```
./configure.sh -N
./configure.sh --disable-nls
```
<a name="build-extra-math"/>
Both commands are equivalent.
NLS (locale support) is automatically disabled when building for Windows or on
another platform that does not support the POSIX locale API or utilities.
### Extra Math
@ -281,26 +333,94 @@ There is no assignment version of `$` because it is a unary operator.
The assignment versions of the above operators are not available in `dc`, but
the others are, as the operators `$`, `@`, `H`, and `h`, respectively.
Extra operators can be disabled using the `-E` flag in the configure step:
Extra operators can be disabled by passing either the `-E` flag or the
`--disable-extra-math` option to `configure.sh`, as follows:
```
./configure.sh -E
./configure.sh --disable-extra-math
```
Both commands are equivalent.
This `bc` also has a larger library that is only enabled if extra operators are.
More information about the functions can be found in the
[Extended Library](./bc.md#extended-library) section of the
[full manual](./bc.md).
### Manpages
To disable installing manpages, pass either the `-M` flag or the
`--disable-man-pages` option to `configure.sh` as follows:
```
./configure.sh -M
./configure.sh --disable-man-pages
```
Both commands are equivalent.
### Karatsuba Length
The Karatsuba length is the point at which `bc` and `dc` switch from Karatsuba
multiplication to brute force, `O(n^2)` multiplication. It can be set by passing
the `-k` flag or the `--karatsuba-len` option to `configure.sh` as follows:
```
./configure.sh -k64
./configure.sh --karatsuba-len 64
```
Both commands are equivalent.
***WARNING***: The Karatsuba Length must be a **integer** greater than or equal
to `16`. If it is not, `configure.sh` will give an error.
### Install Options
The relevant `autotools`-style install options are supported in `configure.sh`:
* `--prefix`
* `--bindir`
* `--datarootdir`
* `--datadir`
* `--mandir`
* `--man1dir`
* `--localedir`
An example is:
```
./configure.sh --prefix=/usr --localedir /usr/share/nls
make
make install
```
They correspond to the environment variables `$PREFIX`, `$BINDIR`,
`$DATAROOTDIR`, `$DATADIR`, `$MANDIR`, `$MAN1DIR`, and `$LOCALEDIR`,
respectively.
***WARNING***: If the option is given, the value of the corresponding
environment variable is overridden.
## Optimization
The `configure.sh` script will accept an optimization level to pass to the
compiler. Because `bc` is orders of magnitude faster with optimization, I
***highly*** recommend package and distro maintainers pass the highest
optimization level available in `CC` to `configure.sh`, as follows:
optimization level available in `CC` to `configure.sh` with the `-O` flag or
`--opt` option, as follows:
```
./configure.sh -O3
./configure.sh --opt 3
```
Both commands are equivalent.
The build and install can then be run as normal:
```
make
make install
```
@ -323,10 +443,19 @@ in the link stage.
## Debug Builds
Debug builds (which also disable optimization if no optimization level is given
and if no extra `CFLAGS` are given) can be enabled with:
and if no extra `CFLAGS` are given) can be enabled with either the `-g` flag or
the `--debug` option, as follows:
```
./configure.sh -g
./configure.sh --debug
```
Both commands are equivalent.
The build and install can then be run as normal:
```
make
make install
```
@ -347,8 +476,8 @@ There are several reasons that history is a bigger user of space than `dc`
itself:
* `dc`'s lexer and parser are *tiny* compared to `bc`'s.
* `dc` does not have much extra code for runtime.
* History has a lot of const data for supporting UTF-8 terminals.
* `dc` does not have much extra code in the interpreter.
* History has a lot of const data for supporting `UTF-8` terminals.
The next biggest user is `dc`, so if just `bc` is needed, the size can be
reduced to 89 kb (88,624 bytes) with history and 76 kb (76,256 bytes) without
@ -371,24 +500,50 @@ The default test suite can be run with the following command:
make test
```
All available tests can be run by running the following command:
To test `bc` only, run the following command:
```
make test_all
make test_bc
```
This `bc`, if built, assumes a working, GNU-compatible `bc` in the `PATH` to
generate some tests, unless the `-G` option is given to `configure.sh`, as
follows:
To test `dc` only, run the following command:
```
make test_dc
```
This `bc`, if built, assumes a working, GNU-compatible `bc`, installed on the
system and in the `PATH`, to generate some tests, unless the `-G` flag or
`--disable-generated-tests` option is given to `configure.sh`, as follows:
```
./configure.sh -G
./configure.sh --disable-generated-tests
```
After running `configure.sh`, build and run tests as follows:
```
make
make test
```
This `dc` also assumes a working, GNU-compatible `dc` in the `PATH` to generate
some tests, unless the above option is given to `configure.sh`.
This `dc` also assumes a working, GNU-compatible `dc`, installed on the system
and in the `PATH`, to generate some tests, unless on of the above options is
given to `configure.sh`.
To generate test coverage, pass the `-c` flag or the `--coverage` option to
`configure.sh` as follows:
```
./configure.sh -c
./configure.sh --coverage
```
Both commands are equivalent.
***WARNING***: Both `bc` and `dc` must be built for test coverage. Otherwise,
`configure.sh` will give an error.
[1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
[2]: https://www.gnu.org/software/bc/

Loading…
Cancel
Save