contrib/bc/manuals/build.md

   1 # Build
   2
   3 This `bc` attempts to be as portable as possible. It can be built on any
   4 POSIX-compliant system.
   5
   6 To accomplish that, a POSIX-compatible, custom `configure.sh` script is used to
   7 select build options, compiler, and compiler flags and generate a `Makefile`.
   8
   9 The general form of configuring, building, and installing this `bc` is as
  10 follows:
  11
  12 ```
  13 [ENVIRONMENT_VARIABLE=<value>...] ./configure.sh [build_options...]
  14 make
  15 make install
  16 ```
  17
  18 To get all of the options, including any useful environment variables, use
  19 either one of the following commands:
  20
  21 ```
  22 ./configure.sh -h
  23 ./configure.sh --help
  24 ```
  25
  26 ***WARNING***: even though `configure.sh` supports both option types, short and
  27 long, it does not support handling both at the same time. Use only one type.
  28
  29 To learn the available `make` targets run the following command after running
  30 the `configure.sh` script:
  31
  32 ```
  33 make help
  34 ```
  35
  36 See [Build Environment Variables][4] for a more detailed description of all
  37 accepted environment variables and [Build Options][5] for more detail about all
  38 accepted build options.
  39
  40 ## Windows
  41
  42 For releases, Windows builds of `bc`, `dc`, and `bcl` are available for download
  43 from <https://git.gavinhoward.com/gavin/bc> and GitHub.
  44
  45 However, if you wish to build it yourself, this `bc` can be built using Visual
  46 Studio or MSBuild.
  47
  48 Unfortunately, only one build configuration (besides Debug or Release) is
  49 supported: extra math and history enabled, NLS (locale support) disabled, with
  50 both calculators built. The default [settings][11] are `BC_BANNER=1`,
  51 `{BC,DC}_SIGINT_RESET=0`, `{BC,DC}_TTY_MODE=1`, `{BC,DC}_PROMPT=1`.
  52
  53 The library can also be built on Windows.
  54
  55 ### Visual Studio
  56
  57 In Visual Studio, open up the solution file (`bc.sln` for `bc`, or `bcl.sln` for
  58 the library), select the desired configuration, and build.
  59
  60 ### MSBuild
  61
  62 To build with MSBuild, first, *be sure that you are using the MSBuild that comes
  63 with Visual Studio*.
  64
  65 To build `bc`, run the following from the root directory:
  66
  67 ```
  68 msbuild -property:Configuration=<config> vs/bc.sln
  69 ```
  70
  71 where `<config>` is either one of `Debug` or `Release`.
  72
  73 To build the library, run the following from the root directory:
  74
  75 ```
  76 msbuild -property:Configuration=<config> vs/bcl.sln
  77 ```
  78
  79 where `<config>` is either one of `Debug`, `ReleaseMD`, or `ReleaseMT`.
  80
  81 ## POSIX-Compatible Systems
  82
  83 Building `bc`, `dc`, and `bcl` (the library) is more complex than on Windows
  84 because many build options are supported.
  85
  86 ### Out-of-Source Builds
  87
  88 Out-of-source builds are done by calling `configure.sh` from the directory where
  89 the build will happen. The `Makefile` is generated into that directory, and the
  90 build can happen normally from there.
  91
  92 For example, if the source is in `bc`, the build should happen in `build`, then
  93 call `configure.sh` and `make` like so:
  94
  95 ```
  96 ../bc/configure.sh
  97 make
  98 ```
  99
 100 ***WARNING***: The path to `configure.sh` from the build directory must not have
 101 spaces because `make` does not support target names with spaces.
 102
 103 ### Cross Compiling
 104
 105 To cross-compile this `bc`, an appropriate compiler must be present and assigned
 106 to the environment variable `HOSTCC` or `HOST_CC` (the two are equivalent,
 107 though `HOSTCC` is prioritized). This is in order to bootstrap core file(s), if
 108 the architectures are not compatible (i.e., unlike i686 on x86_64). Thus, the
 109 approach is:
 110
 111 ```
 112 HOSTCC="/path/to/native/compiler" ./configure.sh
 113 make
 114 make install
 115 ```
 116
 117 `HOST_CC` will work in exactly the same way.
 118
 119 `HOSTCFLAGS` and `HOST_CFLAGS` can be used to set compiler flags for `HOSTCC`.
 120 (The two are equivalent, as `HOSTCC` and `HOST_CC` are.) `HOSTCFLAGS` is
 121 prioritized over `HOST_CFLAGS`. If neither are present, `HOSTCC` (or `HOST_CC`)
 122 uses `CFLAGS` (see [Build Environment Variables][4] for more details).
 123
 124 It is expected that `CC` produces code for the target system and `HOSTCC`
 125 produces code for the host system. See [Build Environment Variables][4] for more
 126 details.
 127
 128 If an emulator is necessary to run the bootstrap binaries, it can be set with
 129 the environment variable `GEN_EMU`.
 130
 131 ### Build Environment Variables
 132
 133 This `bc` supports `CC`, `HOSTCC`, `HOST_CC`, `CFLAGS`, `HOSTCFLAGS`,
 134 `HOST_CFLAGS`, `CPPFLAGS`, `LDFLAGS`, `LDLIBS`, `PREFIX`, `DESTDIR`, `BINDIR`,
 135 `DATAROOTDIR`, `DATADIR`, `MANDIR`, `MAN1DIR`, `MAN3DIR`, `EXECSUFFIX`,
 136 `EXECPREFIX`, `LONG_BIT`, `GEN_HOST`, and `GEN_EMU` environment variables in
 137 `configure.sh`. Any values of those variables given to `configure.sh` will be
 138 put into the generated Makefile.
 139
 140 More detail on what those environment variables do can be found in the following
 141 sections.
 142
 143 #### `CC`
 144
 145 C compiler for the target system. `CC` must be compatible with POSIX `c99`
 146 behavior and options. However, **I encourage users to use any C99 or C11
 147 compatible compiler they wish.**
 148
 149 If there is a space in the basename of the compiler, the items after the first
 150 space are assumed to be compiler flags, and in that case, the flags are
 151 automatically moved into CFLAGS.
 152
 153 Defaults to `c99`.
 154
 155 #### `HOSTCC` or `HOST_CC`
 156
 157 C compiler for the host system, used only in [cross compiling][6]. Must be
 158 compatible with POSIX `c99` behavior and options.
 159
 160 If there is a space in the basename of the compiler, the items after the first
 161 space are assumed to be compiler flags, and in that case, the flags are
 162 automatically moved into HOSTCFLAGS.
 163
 164 Defaults to `$CC`.
 165
 166 #### `CFLAGS`
 167
 168 Command-line flags that will be passed verbatim to `CC`.
 169
 170 Defaults to empty.
 171
 172 #### `HOSTCFLAGS` or `HOST_CFLAGS`
 173
 174 Command-line flags that will be passed verbatim to `HOSTCC` or `HOST_CC`.
 175
 176 Defaults to `$CFLAGS`.
 177
 178 #### `CPPFLAGS`
 179
 180 Command-line flags for the C preprocessor. These are also passed verbatim to
 181 both compilers (`CC` and `HOSTCC`); they are supported just for legacy reasons.
 182
 183 Defaults to empty.
 184
 185 #### `LDFLAGS`
 186
 187 Command-line flags for the linker. These are also passed verbatim to both
 188 compilers (`CC` and `HOSTCC`); they are supported just for legacy reasons.
 189
 190 Defaults to empty.
 191
 192 #### `LDLIBS`
 193
 194 Libraries to link to. These are also passed verbatim to both compilers (`CC` and
 195 `HOSTCC`); they are supported just for legacy reasons and for cross compiling
 196 with different C standard libraries (like [musl][3]).
 197
 198 Defaults to empty.
 199
 200 #### `PREFIX`
 201
 202 The prefix to install to.
 203
 204 Can be overridden by passing the `--prefix` option to `configure.sh`.
 205
 206 Defaults to `/usr/local`.
 207
 208 ***WARNING***: Locales ignore the prefix because they *must* be installed at a
 209 fixed location to work at all. If you do not want that to happen, you must
 210 disable locales (NLS) completely.
 211
 212 #### `DESTDIR`
 213
 214 Path to prepend onto `PREFIX`. This is mostly for distro and package
 215 maintainers.
 216
 217 This can be passed either to `configure.sh` or `make install`. If it is passed
 218 to both, the one given to `configure.sh` takes precedence.
 219
 220 Defaults to empty.
 221
 222 #### `BINDIR`
 223
 224 The directory to install binaries in.
 225
 226 Can be overridden by passing the `--bindir` option to `configure.sh`.
 227
 228 Defaults to `$PREFIX/bin`.
 229
 230 #### `INCLUDEDIR`
 231
 232 The directory to install header files in.
 233
 234 Can be overridden by passing the `--includedir` option to `configure.sh`.
 235
 236 Defaults to `$PREFIX/include`.
 237
 238 #### `LIBDIR`
 239
 240 The directory to install libraries in.
 241
 242 Can be overridden by passing the `--libdir` option to `configure.sh`.
 243
 244 Defaults to `$PREFIX/lib`.
 245
 246 #### `DATAROOTDIR`
 247
 248 The root directory to install data files in.
 249
 250 Can be overridden by passing the `--datarootdir` option to `configure.sh`.
 251
 252 Defaults to `$PREFIX/share`.
 253
 254 #### `DATADIR`
 255
 256 The directory to install data files in.
 257
 258 Can be overridden by passing the `--datadir` option to `configure.sh`.
 259
 260 Defaults to `$DATAROOTDIR`.
 261
 262 #### `MANDIR`
 263
 264 The directory to install manpages in.
 265
 266 Can be overridden by passing the `--mandir` option to `configure.sh`.
 267
 268 Defaults to `$DATADIR/man`
 269
 270 #### `MAN1DIR`
 271
 272 The directory to install Section 1 manpages in. Because both `bc` and `dc` are
 273 Section 1 commands, this is the only relevant section directory.
 274
 275 Can be overridden by passing the `--man1dir` option to `configure.sh`.
 276
 277 Defaults to `$MANDIR/man1`.
 278
 279 #### `MAN3DIR`
 280
 281 The directory to install Section 3 manpages in.
 282
 283 Can be overridden by passing the `--man3dir` option to `configure.sh`.
 284
 285 Defaults to `$MANDIR/man3`.
 286
 287 #### `EXECSUFFIX`
 288
 289 The suffix to append onto the executable names *when installing*. This is for
 290 packagers and distro maintainers who want this `bc` as an option, but do not
 291 want to replace the default `bc`.
 292
 293 Defaults to empty.
 294
 295 #### `EXECPREFIX`
 296
 297 The prefix to append onto the executable names *when building and installing*.
 298 This is for packagers and distro maintainers who want this `bc` as an option,
 299 but do not want to replace the default `bc`.
 300
 301 Defaults to empty.
 302
 303 #### `LONG_BIT`
 304
 305 The number of bits in a C `long` type. This is mostly for the embedded space.
 306
 307 This `bc` uses `long`s internally for overflow checking. In C99, a `long` is
 308 required to be 32 bits. For this reason, on 8-bit and 16-bit microcontrollers,
 309 the generated code to do math with `long` types may be inefficient.
 310
 311 For most normal desktop systems, setting this is unnecessary, except that 32-bit
 312 platforms with 64-bit longs may want to set it to `32`.
 313
 314 Defaults to the default value of `LONG_BIT` for the target platform. For
 315 compliance with the `bc` spec, the minimum allowed value is `32`.
 316
 317 It is an error if the specified value is greater than the default value of
 318 `LONG_BIT` for the target platform.
 319
 320 #### `GEN_HOST`
 321
 322 Whether to use `gen/strgen.c`, instead of `gen/strgen.sh`, to produce the C
 323 files that contain the help texts as well as the math libraries. By default,
 324 `gen/strgen.c` is used, compiled by `$HOSTCC` and run on the host machine. Using
 325 `gen/strgen.sh` removes the need to compile and run an executable on the host
 326 machine since `gen/strgen.sh` is a POSIX shell script. However, `gen/lib2.bc` is
 327 perilously close to 4095 characters, the max supported length of a string
 328 literal in C99 (and it could be added to in the future), and `gen/strgen.sh`
 329 generates a string literal instead of an array, as `gen/strgen.c` does. For most
 330 production-ready compilers, this limit probably is not enforced, but it could
 331 be. Both options are still available for this reason.
 332
 333 If you are sure your compiler does not have the limit and do not want to compile
 334 and run a binary on the host machine, set this variable to "0". Any other value,
 335 or a non-existent value, will cause the build system to compile and run
 336 `gen/strgen.c`.
 337
 338 Default is "".
 339
 340 #### `GEN_EMU`
 341
 342 The emulator to run bootstrap binaries under. This is only if the binaries
 343 produced by `HOSTCC` (or `HOST_CC`) need to be run under an emulator to work.
 344
 345 Defaults to empty.
 346
 347 ### Build Options
 348
 349 This `bc` comes with several build options, all of which are enabled by default.
 350
 351 All options can be used with each other, with a few exceptions that will be
 352 noted below.
 353
 354 **NOTE**: All long options with mandatory argumenst accept either one of the
 355 following forms:
 356
 357 ```
 358 --option arg
 359 --option=arg
 360 ```
 361
 362 #### Predefined Builds
 363
 364 To quickly get a release build of a `bc` and `dc` that is (by default)
 365 compatible with the BSD `bc` and `dc`, use the `-p` or `--predefined-build-type`
 366 options:
 367
 368 ```
 369 ./configure.sh -pBSD
 370 ./configure.sh --predefined-build-type=BSD
 371 ```
 372
 373 Both commands are equivalent.
 374
 375 To quickly get a release build of a `bc` and `dc` that is (by default)
 376 compatible with the GNU `bc` and `dc`, use the `-p` or `--predefined-build-type`
 377 options:
 378
 379 ```
 380 ./configure.sh -pGNU
 381 ./configure.sh --predefined-build-type=GNU
 382 ```
 383
 384 Both commands are equivalent.
 385
 386 #### Library
 387
 388 To build the math library, use the following commands for the configure step:
 389
 390 ```
 391 ./configure.sh -a
 392 ./configure.sh --library
 393 ```
 394
 395 Both commands are equivalent.
 396
 397 When the library is built, history and locales are disabled, and the
 398 functionality for `bc` and `dc` are both enabled, though the executables are
 399 *not* built. This is because the library's options clash with the executables.
 400
 401 To build an optimized version of the library, users can pass optimization
 402 options to `configure.sh` or include them in `CFLAGS`.
 403
 404 The library API can be found in `manuals/bcl.3.md` or `man bcl` once the library
 405 is installed.
 406
 407 The library is built as `bin/libbcl.a`.
 408
 409 #### `bc` Only
 410
 411 To build `bc` only (no `dc`), use any one of the following commands for the
 412 configure step:
 413
 414 ```
 415 ./configure.sh -b
 416 ./configure.sh --bc-only
 417 ./configure.sh -D
 418 ./configure.sh --disable-dc
 419 ```
 420
 421 Those commands are all equivalent.
 422
 423 ***Warning***: It is an error to use those options if `bc` has also been
 424 disabled (see below).
 425
 426 #### `dc` Only
 427
 428 To build `dc` only (no `bc`), use either one of the following commands for the
 429 configure step:
 430
 431 ```
 432 ./configure.sh -d
 433 ./configure.sh --dc-only
 434 ./configure.sh -B
 435 ./configure.sh --disable-bc
 436 ```
 437
 438 Those commands are all equivalent.
 439
 440 ***Warning***: It is an error to use those options if `dc` has also been
 441 disabled (see above).
 442
 443 #### History
 444
 445 To disable hisory, pass either the `-H` flag or the `--disable-history` option
 446 to `configure.sh`, as follows:
 447
 448 ```
 449 ./configure.sh -H
 450 ./configure.sh --disable-history
 451 ```
 452
 453 Both commands are equivalent.
 454
 455 ***WARNING***: Of all of the code in the `bc`, this is the only code that is not
 456 completely portable. If the `bc` does not work on your platform, your first step
 457 should be to retry with history disabled.
 458
 459 This option affects the [build type][7].
 460
 461 ##### Editline
 462
 463 History support can be provided by editline, in order to implement `vi`-like
 464 keybindings and other features.
 465
 466 To enable editline support, pass either the `-e` flag or the `--enable-editline`
 467 option to `configure.sh`, as follows:
 468
 469 ```
 470 ./configure.sh -e
 471 ./configure.sh --enable-editline
 472 ```
 473
 474 Both commands are equivalent.
 475
 476 This is ignored if history is disabled.
 477
 478 This option is only used if it is after any other `-e`/`--enable-editline`
 479 options, any `-r`/`--enable-readline` options, and any
 480 `-i`/`--enable-internal-history` options.
 481
 482 ##### Readline
 483
 484 History support can be provided by readline, in order to implement `vi`-like
 485 keybindings and other features.
 486
 487 To enable readline support, pass either the `-r` flag or the `--enable-readline`
 488 option to `configure.sh`, as follows:
 489
 490 ```
 491 ./configure.sh -r
 492 ./configure.sh --enable-readline
 493 ```
 494
 495 Both commands are equivalent.
 496
 497 This is ignored if history is disabled.
 498
 499 This option is only used if it is after any other `-r`/`--enable-readline`
 500 options, any `-e`/`--enable-editline` options, and any
 501 `-i`/`--enable-internal-history` options.
 502
 503 ##### Internal History
 504
 505 History support is also available as an internal implementation with no
 506 dependencies. This is the default if editline and readline are not selected.
 507
 508 However, if `-p` option is used, then this option can be useful for selecting
 509 the internal history regardless of what the predefined build has.
 510
 511 To enable the internal history, pass either the `-i` flag or the
 512 `--enable-internal-history` option to `configure.sh` as follows:
 513
 514 ```
 515 ./configure.sh -i
 516 ./configure.sh --enable-internal-history
 517 ```
 518
 519 This option is only used if it is after any other
 520 `-i`/`--enable-internal-history` options, any `-e`/`--enable-editline` options,
 521 and any `-r`/`--enable-readline` options.
 522
 523 #### NLS (Locale Support)
 524
 525 To disable locale support (use only English), pass either the `-N` flag or the
 526 `--disable-nls` option to `configure.sh`, as follows:
 527
 528 ```
 529 ./configure.sh -N
 530 ./configure.sh --disable-nls
 531 ```
 532
 533 Both commands are equivalent.
 534
 535 NLS (locale support) is automatically disabled when building for Windows or on
 536 another platform that does not support the POSIX locale API or utilities.
 537
 538 This option affects the [build type][7].
 539
 540 ***WARNING***: Locales ignore the prefix because they *must* be installed at a
 541 fixed location to work at all. If you do not want that to happen, you must
 542 disable locales (NLS) completely.
 543
 544 #### Extra Math
 545
 546 This `bc` has 7 extra operators:
 547
 548 * `$` (truncation to integer)
 549 * `@` (set precision)
 550 * `@=` (set precision and assign)
 551 * `<<` (shift number left, shifts radix right)
 552 * `<<=` (shift number left and assign)
 553 * `>>` (shift number right, shifts radix left)
 554 * `>>=` (shift number right and assign)
 555
 556 There is no assignment version of `$` because it is a unary operator.
 557
 558 The assignment versions of the above operators are not available in `dc`, but
 559 the others are, as the operators `$`, `@`, `H`, and `h`, respectively.
 560
 561 In addition, this `bc` has the option of outputting in scientific notation or
 562 engineering notation. It can also take input in scientific or engineering
 563 notation. On top of that, it has a pseudo-random number generator. (See the
 564 full manual for more details.)
 565
 566 Extra operators, scientific notation, engineering notation, and the
 567 pseudo-random number generator can be disabled by passing either the `-E` flag
 568 or the `--disable-extra-math` option to `configure.sh`, as follows:
 569
 570 ```
 571 ./configure.sh -E
 572 ./configure.sh --disable-extra-math
 573 ```
 574
 575 Both commands are equivalent.
 576
 577 This `bc` also has a larger library that is only enabled if extra operators and
 578 the pseudo-random number generator are. More information about the functions can
 579 be found in the Extended Library section of the full manual.
 580
 581 This option affects the [build type][7].
 582
 583 #### Karatsuba Length
 584
 585 The Karatsuba length is the point at which `bc` and `dc` switch from Karatsuba
 586 multiplication to brute force, `O(n^2)` multiplication. It can be set by passing
 587 the `-k` flag or the `--karatsuba-len` option to `configure.sh` as follows:
 588
 589 ```
 590 ./configure.sh -k32
 591 ./configure.sh --karatsuba-len 32
 592 ```
 593
 594 Both commands are equivalent.
 595
 596 Default is `32`.
 597
 598 ***WARNING***: The Karatsuba Length must be a **integer** greater than or equal
 599 to `16` (to prevent stack overflow). If it is not, `configure.sh` will give an
 600 error.
 601
 602 #### Settings
 603
 604 This `bc` and `dc` have a few settings to override default behavior.
 605
 606 The defaults for these settings can be set by package maintainers, and the
 607 settings themselves can be overriden by users.
 608
 609 To set a default to **on**, use the `-s` or `--set-default-on` option to
 610 `configure.sh`, with the name of the setting, as follows:
 611
 612 ```
 613 ./configure.sh -s bc.banner
 614 ./configure.sh --set-default-on=bc.banner
 615 ```
 616
 617 Both commands are equivalent.
 618
 619 To set a default to **off**, use the `-S` or `--set-default-off` option to
 620 `configure.sh`, with the name of the setting, as follows:
 621
 622 ```
 623 ./configure.sh -S bc.banner
 624 ./configure.sh --set-default-off=bc.banner
 625 ```
 626
 627 Both commands are equivalent.
 628
 629 Users can override the default settings set by packagers with environment
 630 variables. If the environment variable has an integer, then the setting is
 631 turned **on** for a non-zero integer, and **off** for zero.
 632
 633 The table of the available settings, along with their defaults and the
 634 environment variables to override them, is below:
 635
 636 ```
 637 | Setting         | Description          | Default      | Env Variable         |
 638 | =============== | ==================== | ============ | ==================== |
 639 | bc.banner       | Whether to display   |            0 | BC_BANNER            |
 640 |                 | the bc version       |              |                      |
 641 |                 | banner when in       |              |                      |
 642 |                 | interactive mode.    |              |                      |
 643 | --------------- | -------------------- | ------------ | -------------------- |
 644 | bc.sigint_reset | Whether SIGINT will  |            1 | BC_SIGINT_RESET      |
 645 |                 | reset bc, instead of |              |                      |
 646 |                 | exiting, when in     |              |                      |
 647 |                 | interactive mode.    |              |                      |
 648 | --------------- | -------------------- | ------------ | -------------------- |
 649 | dc.sigint_reset | Whether SIGINT will  |            1 | DC_SIGINT_RESET      |
 650 |                 | reset dc, instead of |              |                      |
 651 |                 | exiting, when in     |              |                      |
 652 |                 | interactive mode.    |              |                      |
 653 | --------------- | -------------------- | ------------ | -------------------- |
 654 | bc.tty_mode     | Whether TTY mode for |            1 | BC_TTY_MODE          |
 655 |                 | bc should be on when |              |                      |
 656 |                 | available.           |              |                      |
 657 | --------------- | -------------------- | ------------ | -------------------- |
 658 | dc.tty_mode     | Whether TTY mode for |            0 | BC_TTY_MODE          |
 659 |                 | dc should be on when |              |                      |
 660 |                 | available.           |              |                      |
 661 | --------------- | -------------------- | ------------ | -------------------- |
 662 | bc.prompt       | Whether the prompt   | $BC_TTY_MODE | BC_PROMPT            |
 663 |                 | for bc should be on  |              |                      |
 664 |                 | in tty mode.         |              |                      |
 665 | --------------- | -------------------- | ------------ | -------------------- |
 666 | dc.prompt       | Whether the prompt   | $DC_TTY_MODE | DC_PROMPT            |
 667 |                 | for dc should be on  |              |                      |
 668 |                 | in tty mode.         |              |                      |
 669 | --------------- | -------------------- | ------------ | -------------------- |
 670 | bc.expr_exit    | Whether to exit bc   |            1 | BC_EXPR_EXIT         |
 671 |                 | if an expression or  |              |                      |
 672 |                 | expression file is   |              |                      |
 673 |                 | given with the -e or |              |                      |
 674 |                 | -f options.          |              |                      |
 675 | --------------- | -------------------- | ------------ | -------------------- |
 676 | dc.expr_exit    | Whether to exit dc   |            1 | DC_EXPR_EXIT         |
 677 |                 | if an expression or  |              |                      |
 678 |                 | expression file is   |              |                      |
 679 |                 | given with the -e or |              |                      |
 680 |                 | -f options.          |              |                      |
 681 | --------------- | -------------------- | ------------ | -------------------- |
 682 | bc.digit_clamp  | Whether to have bc   |            0 | BC_DIGIT_CLAMP       |
 683 |                 | clamp digits that    |              |                      |
 684 |                 | are greater than or  |              |                      |
 685 |                 | equal to the current |              |                      |
 686 |                 | ibase when parsing   |              |                      |
 687 |                 | numbers.             |              |                      |
 688 | --------------- | -------------------- | ------------ | -------------------- |
 689 | dc.digit_clamp  | Whether to have dc   |            0 | DC_DIGIT_CLAMP       |
 690 |                 | clamp digits that    |              |                      |
 691 |                 | are greater than or  |              |                      |
 692 |                 | equal to the current |              |                      |
 693 |                 | ibase when parsing   |              |                      |
 694 |                 | numbers.             |              |                      |
 695 | --------------- | -------------------- | ------------ | -------------------- |
 696 ```
 697
 698 These settings are not meant to be changed on a whim. They are meant to ensure
 699 that this bc and dc will conform to the expectations of the user on each
 700 platform.
 701
 702 #### Install Options
 703
 704 The relevant `autotools`-style install options are supported in `configure.sh`:
 705
 706 * `--prefix`
 707 * `--bindir`
 708 * `--datarootdir`
 709 * `--datadir`
 710 * `--mandir`
 711 * `--man1dir`
 712 * `--man3dir`
 713
 714 An example is:
 715
 716 ```
 717 ./configure.sh --prefix=/usr
 718 make
 719 make install
 720 ```
 721
 722 They correspond to the environment variables `$PREFIX`, `$BINDIR`,
 723 `$DATAROOTDIR`, `$DATADIR`, `$MANDIR`, `$MAN1DIR`, `$MAN3DIR`, and respectively.
 724
 725 ***WARNING***: Locales ignore the prefix because they *must* be installed at a
 726 fixed location to work at all. If you do not want that to happen, you must
 727 disable locales (NLS) completely.
 728
 729 ***WARNING***: If the option is given, the value of the corresponding
 730 environment variable is overridden.
 731
 732 ***WARNING***: If any long command-line options are used, the long form of all
 733 other command-line options must be used. Mixing long and short options is not
 734 supported.
 735
 736 ##### Manpages
 737
 738 To disable installing manpages, pass either the `-M` flag or the
 739 `--disable-man-pages` option to `configure.sh` as follows:
 740
 741 ```
 742 ./configure.sh -M
 743 ./configure.sh --disable-man-pages
 744 ```
 745
 746 Both commands are equivalent.
 747
 748 ##### Locales
 749
 750 By default, `bc` and `dc` do not install all locales, but only the enabled
 751 locales. If `DESTDIR` exists and is not empty, then they will install all of
 752 the locales that exist on the system. The `-l` flag or `--install-all-locales`
 753 option skips all of that and just installs all of the locales that `bc` and `dc`
 754 have, regardless. To enable that behavior, you can pass the `-l` flag or the
 755 `--install-all-locales` option to `configure.sh`, as follows:
 756
 757 ```
 758 ./configure.sh -l
 759 ./configure.sh --install-all-locales
 760 ```
 761
 762 Both commands are equivalent.
 763
 764 ***WARNING***: Locales ignore the prefix because they *must* be installed at a
 765 fixed location to work at all. If you do not want that to happen, you must
 766 disable locales (NLS) completely.
 767
 768 ### Optimization
 769
 770 The `configure.sh` script will accept an optimization level to pass to the
 771 compiler. Because `bc` is orders of magnitude faster with optimization, I
 772 ***highly*** recommend package and distro maintainers pass the highest
 773 optimization level available in `CC` to `configure.sh` with the `-O` flag or
 774 `--opt` option, as follows:
 775
 776 ```
 777 ./configure.sh -O3
 778 ./configure.sh --opt 3
 779 ```
 780
 781 Both commands are equivalent.
 782
 783 The build and install can then be run as normal:
 784
 785 ```
 786 make
 787 make install
 788 ```
 789
 790 As usual, `configure.sh` will also accept additional `CFLAGS` on the command
 791 line, so for SSE4 architectures, the following can add a bit more speed:
 792
 793 ```
 794 CFLAGS="-march=native -msse4" ./configure.sh -O3
 795 make
 796 make install
 797 ```
 798
 799 Building with link-time optimization (`-flto` in clang) can further increase the
 800 performance. I ***highly*** recommend doing so.
 801
 802 I do ***NOT*** recommend building with `-march=native`; doing so reduces this
 803 `bc`'s performance.
 804
 805 Manual stripping is not necessary; non-debug builds are automatically stripped
 806 in the link stage.
 807
 808 ### Debug Builds
 809
 810 Debug builds (which also disable optimization if no optimization level is given
 811 and if no extra `CFLAGS` are given) can be enabled with either the `-g` flag or
 812 the `--debug` option, as follows:
 813
 814 ```
 815 ./configure.sh -g
 816 ./configure.sh --debug
 817 ```
 818
 819 Both commands are equivalent.
 820
 821 The build and install can then be run as normal:
 822
 823 ```
 824 make
 825 make install
 826 ```
 827
 828 ### Stripping Binaries
 829
 830 By default, when `bc` and `dc` are not built in debug mode, the binaries are
 831 stripped. Stripping can be disabled with either the `-T` or the
 832 `--disable-strip` option, as follows:
 833
 834 ```
 835 ./configure.sh -T
 836 ./configure.sh --disable-strip
 837 ```
 838
 839 Both commands are equivalent.
 840
 841 The build and install can then be run as normal:
 842
 843 ```
 844 make
 845 make install
 846 ```
 847
 848 ### Build Type
 849
 850 `bc` and `dc` have 8 build types, affected by the [History][8], [NLS (Locale
 851 Support)][9], and [Extra Math][10] build options.
 852
 853 The build types are as follows:
 854
 855 * `A`: Nothing disabled.
 856 * `E`: Extra math disabled.
 857 * `H`: History disabled.
 858 * `N`: NLS disabled.
 859 * `EH`: Extra math and History disabled.
 860 * `EN`: Extra math and NLS disabled.
 861 * `HN`: History and NLS disabled.
 862 * `EHN`: Extra math, History, and NLS all disabled.
 863
 864 These build types correspond to the generated manuals in `manuals/bc` and
 865 `manuals/dc`.
 866
 867 ### Binary Size
 868
 869 When built with both calculators, all available features, and `-Os` using
 870 `clang` and `musl`, the executable is 140.4 kb (140,386 bytes) on `x86_64`. That
 871 isn't much for what is contained in the binary, but if necessary, it can be
 872 reduced.
 873
 874 The single largest user of space is the `bc` calculator. If just `dc` is needed,
 875 the size can be reduced to 107.6 kb (107,584 bytes).
 876
 877 The next largest user of space is history support. If that is not needed, size
 878 can be reduced (for a build with both calculators) to 119.9 kb (119,866 bytes).
 879
 880 There are several reasons that history is a bigger user of space than `dc`
 881 itself:
 882
 883 * `dc`'s lexer and parser are *tiny* compared to `bc`'s because `dc` code is
 884   almost already in the form that it is executed in, while `bc` has to not only
 885   adjust the form to be executable, it has to parse functions, loops, `if`
 886   statements, and other extra features.
 887 * `dc` does not have much extra code in the interpreter.
 888 * History has a lot of const data for supporting `UTF-8` terminals.
 889 * History pulls in a bunch of more code from the `libc`.
 890
 891 The next biggest user is extra math support. Without it, the size is reduced to
 892 124.0 kb (123,986 bytes) with history and 107.6 kb (107,560 bytes) without
 893 history.
 894
 895 The reasons why extra math support is bigger than `dc`, besides the fact that
 896 `dc` is small already, are:
 897
 898 * Extra math supports adds an extra math library that takes several kilobytes of
 899   constant data space.
 900 * Extra math support includes support for a pseudo-random number generator,
 901   including the code to convert a series of pseudo-random numbers into a number
 902   of arbitrary size.
 903 * Extra math support adds several operators.
 904
 905 The next biggest user is `dc`, so if just `bc` is needed, the size can be
 906 reduced to 128.1 kb (128,096 bytes) with history and extra math support, 107.6
 907 kb (107,576 bytes) without history and with extra math support, and 95.3 kb
 908 (95,272 bytes) without history and without extra math support.
 909
 910 *Note*: all of these binary sizes were compiled using `musl` `1.2.0` as the
 911 `libc`, making a fully static executable, with `clang` `9.0.1` (well,
 912 `musl-clang` using `clang` `9.0.1`) as the compiler and using `-Os`
 913 optimizations. These builds were done on an `x86_64` machine running Gentoo
 914 Linux.
 915
 916 ### Testing
 917
 918 The default test suite can be run with the following command:
 919
 920 ```
 921 make test
 922 ```
 923
 924 To test `bc` only, run the following command:
 925
 926 ```
 927 make test_bc
 928 ```
 929
 930 To test `dc` only, run the following command:
 931
 932 ```
 933 make test_dc
 934 ```
 935
 936 This `bc`, if built, assumes a working, GNU-compatible `bc`, installed on the
 937 system and in the `PATH`, to generate some tests, unless the `-G` flag or
 938 `--disable-generated-tests` option is given to `configure.sh`, as follows:
 939
 940 ```
 941 ./configure.sh -G
 942 ./configure.sh --disable-generated-tests
 943 ```
 944
 945 After running `configure.sh`, build and run tests as follows:
 946
 947 ```
 948 make
 949 make test
 950 ```
 951
 952 This `dc` also assumes a working, GNU-compatible `dc`, installed on the system
 953 and in the `PATH`, to generate some tests, unless one of the above options is
 954 given to `configure.sh`.
 955
 956 To generate test coverage, pass the `-c` flag or the `--coverage` option to
 957 `configure.sh` as follows:
 958
 959 ```
 960 ./configure.sh -c
 961 ./configure.sh --coverage
 962 ```
 963
 964 Both commands are equivalent.
 965
 966 ***WARNING***: Both `bc` and `dc` must be built for test coverage. Otherwise,
 967 `configure.sh` will give an error.
 968
 969 #### Problematic Tests
 970
 971 Some tests are problematic, in that they can cause `SIGKILL` on FreeBSD or
 972 `SIGSEGV` on Linux from being killed by the "OOM Killer" part of the kernel. On
 973 Linux, these tests are usually fine, but on FreeBSD, they are usually a problem.
 974
 975 To disable problematic tests, pass the `-P` flag or the
 976 `--disable-problematic-tests` option to `configure.sh` as follows:
 977
 978 ```
 979 ./configure.sh -P
 980 ./configure.sh --disable-problematic-tests
 981 ```
 982
 983 Both commands are equivalent.
 984
 985 [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
 986 [2]: https://www.gnu.org/software/bc/
 987 [3]: https://www.musl-libc.org/
 988 [4]: #build-environment-variables
 989 [5]: #build-options
 990 [6]: #cross-compiling
 991 [7]: #build-type
 992 [8]: #history
 993 [9]: #nls-locale-support
 994 [10]: #extra-math
 995 [11]: #settings