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.yzena.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`, `LOCALEDIR` `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 #### `DESTDIR`
 209
 210 Path to prepend onto `PREFIX`. This is mostly for distro and package
 211 maintainers.
 212
 213 This can be passed either to `configure.sh` or `make install`. If it is passed
 214 to both, the one given to `configure.sh` takes precedence.
 215
 216 Defaults to empty.
 217
 218 #### `BINDIR`
 219
 220 The directory to install binaries in.
 221
 222 Can be overridden by passing the `--bindir` option to `configure.sh`.
 223
 224 Defaults to `$PREFIX/bin`.
 225
 226 #### `INCLUDEDIR`
 227
 228 The directory to install header files in.
 229
 230 Can be overridden by passing the `--includedir` option to `configure.sh`.
 231
 232 Defaults to `$PREFIX/include`.
 233
 234 #### `LIBDIR`
 235
 236 The directory to install libraries in.
 237
 238 Can be overridden by passing the `--libdir` option to `configure.sh`.
 239
 240 Defaults to `$PREFIX/lib`.
 241
 242 #### `DATAROOTDIR`
 243
 244 The root directory to install data files in.
 245
 246 Can be overridden by passing the `--datarootdir` option to `configure.sh`.
 247
 248 Defaults to `$PREFIX/share`.
 249
 250 #### `DATADIR`
 251
 252 The directory to install data files in.
 253
 254 Can be overridden by passing the `--datadir` option to `configure.sh`.
 255
 256 Defaults to `$DATAROOTDIR`.
 257
 258 #### `MANDIR`
 259
 260 The directory to install manpages in.
 261
 262 Can be overridden by passing the `--mandir` option to `configure.sh`.
 263
 264 Defaults to `$DATADIR/man`
 265
 266 #### `MAN1DIR`
 267
 268 The directory to install Section 1 manpages in. Because both `bc` and `dc` are
 269 Section 1 commands, this is the only relevant section directory.
 270
 271 Can be overridden by passing the `--man1dir` option to `configure.sh`.
 272
 273 Defaults to `$MANDIR/man1`.
 274
 275 #### `LOCALEDIR`
 276
 277 The directory to install locales in.
 278
 279 Can be overridden by passing the `--localedir` option to `configure.sh`.
 280
 281 Defaults to `$DATAROOTDIR/locale`.
 282
 283 #### `EXECSUFFIX`
 284
 285 The suffix to append onto the executable names *when installing*. This is for
 286 packagers and distro maintainers who want this `bc` as an option, but do not
 287 want to replace the default `bc`.
 288
 289 Defaults to empty.
 290
 291 #### `EXECPREFIX`
 292
 293 The prefix to append onto the executable names *when building and installing*.
 294 This is for packagers and distro maintainers who want this `bc` as an option,
 295 but do not want to replace the default `bc`.
 296
 297 Defaults to empty.
 298
 299 #### `LONG_BIT`
 300
 301 The number of bits in a C `long` type. This is mostly for the embedded space.
 302
 303 This `bc` uses `long`s internally for overflow checking. In C99, a `long` is
 304 required to be 32 bits. For this reason, on 8-bit and 16-bit microcontrollers,
 305 the generated code to do math with `long` types may be inefficient.
 306
 307 For most normal desktop systems, setting this is unnecessary, except that 32-bit
 308 platforms with 64-bit longs may want to set it to `32`.
 309
 310 Defaults to the default value of `LONG_BIT` for the target platform. For
 311 compliance with the `bc` spec, the minimum allowed value is `32`.
 312
 313 It is an error if the specified value is greater than the default value of
 314 `LONG_BIT` for the target platform.
 315
 316 #### `GEN_HOST`
 317
 318 Whether to use `gen/strgen.c`, instead of `gen/strgen.sh`, to produce the C
 319 files that contain the help texts as well as the math libraries. By default,
 320 `gen/strgen.c` is used, compiled by `$HOSTCC` and run on the host machine. Using
 321 `gen/strgen.sh` removes the need to compile and run an executable on the host
 322 machine since `gen/strgen.sh` is a POSIX shell script. However, `gen/lib2.bc` is
 323 perilously close to 4095 characters, the max supported length of a string
 324 literal in C99 (and it could be added to in the future), and `gen/strgen.sh`
 325 generates a string literal instead of an array, as `gen/strgen.c` does. For most
 326 production-ready compilers, this limit probably is not enforced, but it could
 327 be. Both options are still available for this reason.
 328
 329 If you are sure your compiler does not have the limit and do not want to compile
 330 and run a binary on the host machine, set this variable to "0". Any other value,
 331 or a non-existent value, will cause the build system to compile and run
 332 `gen/strgen.c`.
 333
 334 Default is "".
 335
 336 #### `GEN_EMU`
 337
 338 The emulator to run bootstrap binaries under. This is only if the binaries
 339 produced by `HOSTCC` (or `HOST_CC`) need to be run under an emulator to work.
 340
 341 Defaults to empty.
 342
 343 ### Build Options
 344
 345 This `bc` comes with several build options, all of which are enabled by default.
 346
 347 All options can be used with each other, with a few exceptions that will be
 348 noted below.
 349
 350 **NOTE**: All long options with mandatory argumenst accept either one of the
 351 following forms:
 352
 353 ```
 354 --option arg
 355 --option=arg
 356 ```
 357
 358 #### Library
 359
 360 To build the math library, use the following commands for the configure step:
 361
 362 ```
 363 ./configure.sh -a
 364 ./configure.sh --library
 365 ```
 366
 367 Both commands are equivalent.
 368
 369 When the library is built, history and locales are disabled, and the
 370 functionality for `bc` and `dc` are both enabled, though the executables are
 371 *not* built. This is because the library's options clash with the executables.
 372
 373 To build an optimized version of the library, users can pass optimization
 374 options to `configure.sh` or include them in `CFLAGS`.
 375
 376 The library API can be found in `manuals/bcl.3.md` or `man bcl` once the library
 377 is installed.
 378
 379 The library is built as `bin/libbcl.a`.
 380
 381 #### `bc` Only
 382
 383 To build `bc` only (no `dc`), use any one of the following commands for the
 384 configure step:
 385
 386 ```
 387 ./configure.sh -b
 388 ./configure.sh --bc-only
 389 ./configure.sh -D
 390 ./configure.sh --disable-dc
 391 ```
 392
 393 Those commands are all equivalent.
 394
 395 ***Warning***: It is an error to use those options if `bc` has also been
 396 disabled (see below).
 397
 398 #### `dc` Only
 399
 400 To build `dc` only (no `bc`), use either one of the following commands for the
 401 configure step:
 402
 403 ```
 404 ./configure.sh -d
 405 ./configure.sh --dc-only
 406 ./configure.sh -B
 407 ./configure.sh --disable-bc
 408 ```
 409
 410 Those commands are all equivalent.
 411
 412 ***Warning***: It is an error to use those options if `dc` has also been
 413 disabled (see above).
 414
 415 #### History
 416
 417 To disable hisory, pass either the `-H` flag or the `--disable-history` option
 418 to `configure.sh`, as follows:
 419
 420 ```
 421 ./configure.sh -H
 422 ./configure.sh --disable-history
 423 ```
 424
 425 Both commands are equivalent.
 426
 427 ***WARNING***: Of all of the code in the `bc`, this is the only code that is not
 428 completely portable. If the `bc` does not work on your platform, your first step
 429 should be to retry with history disabled.
 430
 431 This option affects the [build type][7].
 432
 433 ##### Editline
 434
 435 History support can be provided by editline, in order to implement `vi`-like
 436 keybindings and other features.
 437
 438 To enable editline support pass either the `-e` flag or the `--enable-editline`
 439 option to `configure.sh`, as follows:
 440
 441 ```
 442 ./configure.sh -e
 443 ./configure.sh --enable-editline
 444 ```
 445
 446 Both commands are equivalent.
 447
 448 This is ignored if history is disabled.
 449
 450 ##### Readline
 451
 452 History support can be provided by readline, in order to implement `vi`-like
 453 keybindings and other features.
 454
 455 To enable readline support pass either the `-r` flag or the `--enable-readline`
 456 option to `configure.sh`, as follows:
 457
 458 ```
 459 ./configure.sh -r
 460 ./configure.sh --enable-readline
 461 ```
 462
 463 Both commands are equivalent.
 464
 465 This is ignored if history is disabled.
 466
 467 #### NLS (Locale Support)
 468
 469 To disable locale support (use only English), pass either the `-N` flag or the
 470 `--disable-nls` option to `configure.sh`, as follows:
 471
 472 ```
 473 ./configure.sh -N
 474 ./configure.sh --disable-nls
 475 ```
 476
 477 Both commands are equivalent.
 478
 479 NLS (locale support) is automatically disabled when building for Windows or on
 480 another platform that does not support the POSIX locale API or utilities.
 481
 482 This option affects the [build type][7].
 483
 484 #### Extra Math
 485
 486 This `bc` has 7 extra operators:
 487
 488 * `$` (truncation to integer)
 489 * `@` (set precision)
 490 * `@=` (set precision and assign)
 491 * `<<` (shift number left, shifts radix right)
 492 * `<<=` (shift number left and assign)
 493 * `>>` (shift number right, shifts radix left)
 494 * `>>=` (shift number right and assign)
 495
 496 There is no assignment version of `$` because it is a unary operator.
 497
 498 The assignment versions of the above operators are not available in `dc`, but
 499 the others are, as the operators `$`, `@`, `H`, and `h`, respectively.
 500
 501 In addition, this `bc` has the option of outputting in scientific notation or
 502 engineering notation. It can also take input in scientific or engineering
 503 notation. On top of that, it has a pseudo-random number generator. (See the
 504 full manual for more details.)
 505
 506 Extra operators, scientific notation, engineering notation, and the
 507 pseudo-random number generator can be disabled by passing either the `-E` flag
 508 or the `--disable-extra-math` option to `configure.sh`, as follows:
 509
 510 ```
 511 ./configure.sh -E
 512 ./configure.sh --disable-extra-math
 513 ```
 514
 515 Both commands are equivalent.
 516
 517 This `bc` also has a larger library that is only enabled if extra operators and
 518 the pseudo-random number generator are. More information about the functions can
 519 be found in the Extended Library section of the full manual.
 520
 521 This option affects the [build type][7].
 522
 523 #### Karatsuba Length
 524
 525 The Karatsuba length is the point at which `bc` and `dc` switch from Karatsuba
 526 multiplication to brute force, `O(n^2)` multiplication. It can be set by passing
 527 the `-k` flag or the `--karatsuba-len` option to `configure.sh` as follows:
 528
 529 ```
 530 ./configure.sh -k32
 531 ./configure.sh --karatsuba-len 32
 532 ```
 533
 534 Both commands are equivalent.
 535
 536 Default is `32`.
 537
 538 ***WARNING***: The Karatsuba Length must be a **integer** greater than or equal
 539 to `16` (to prevent stack overflow). If it is not, `configure.sh` will give an
 540 error.
 541
 542 #### Settings
 543
 544 This `bc` and `dc` have a few settings to override default behavior.
 545
 546 The defaults for these settings can be set by package maintainers, and the
 547 settings themselves can be overriden by users.
 548
 549 To set a default to **on**, use the `-s` or `--set-default-on` option to
 550 `configure.sh`, with the name of the setting, as follows:
 551
 552 ```
 553 ./configure.sh -s bc.banner
 554 ./configure.sh --set-default-on=bc.banner
 555 ```
 556
 557 Both commands are equivalent.
 558
 559 To set a default to **off**, use the `-S` or `--set-default-off` option to
 560 `configure.sh`, with the name of the setting, as follows:
 561
 562 ```
 563 ./configure.sh -S bc.banner
 564 ./configure.sh --set-default-off=bc.banner
 565 ```
 566
 567 Both commands are equivalent.
 568
 569 Users can override the default settings set by packagers with environment
 570 variables. If the environment variable has an integer, then the setting is
 571 turned **on** for a non-zero integer, and **off** for zero.
 572
 573 The table of the available settings, along with their defaults and the
 574 environment variables to override them, is below:
 575
 576 ```
 577 | Setting         | Description          | Default      | Env Variable         |
 578 | =============== | ==================== | ============ | ==================== |
 579 | bc.banner       | Whether to display   |            0 | BC_BANNER            |
 580 |                 | the bc version       |              |                      |
 581 |                 | banner when in       |              |                      |
 582 |                 | interactive mode.    |              |                      |
 583 | --------------- | -------------------- | ------------ | -------------------- |
 584 | bc.sigint_reset | Whether SIGINT will  |            1 | BC_SIGINT_RESET      |
 585 |                 | reset bc, instead of |              |                      |
 586 |                 | exiting, when in     |              |                      |
 587 |                 | interactive mode.    |              |                      |
 588 | --------------- | -------------------- | ------------ | -------------------- |
 589 | dc.sigint_reset | Whether SIGINT will  |            1 | DC_SIGINT_RESET      |
 590 |                 | reset dc, instead of |              |                      |
 591 |                 | exiting, when in     |              |                      |
 592 |                 | interactive mode.    |              |                      |
 593 | --------------- | -------------------- | ------------ | -------------------- |
 594 | bc.tty_mode     | Whether TTY mode for |            1 | BC_TTY_MODE          |
 595 |                 | bc should be on when |              |                      |
 596 |                 | available.           |              |                      |
 597 | --------------- | -------------------- | ------------ | -------------------- |
 598 | dc.tty_mode     | Whether TTY mode for |            0 | BC_TTY_MODE          |
 599 |                 | dc should be on when |              |                      |
 600 |                 | available.           |              |                      |
 601 | --------------- | -------------------- | ------------ | -------------------- |
 602 | bc.prompt       | Whether the prompt   | $BC_TTY_MODE | BC_PROMPT            |
 603 |                 | for bc should be on  |              |                      |
 604 |                 | in tty mode.         |              |                      |
 605 | --------------- | -------------------- | ------------ | -------------------- |
 606 | dc.prompt       | Whether the prompt   | $DC_TTY_MODE | DC_PROMPT            |
 607 |                 | for dc should be on  |              |                      |
 608 |                 | in tty mode.         |              |                      |
 609 | --------------- | -------------------- | ------------ | -------------------- |
 610 ```
 611
 612 These settings are not meant to be changed on a whim. They are meant to ensure
 613 that this bc and dc will conform to the expectations of the user on each
 614 platform.
 615
 616 #### Install Options
 617
 618 The relevant `autotools`-style install options are supported in `configure.sh`:
 619
 620 * `--prefix`
 621 * `--bindir`
 622 * `--datarootdir`
 623 * `--datadir`
 624 * `--mandir`
 625 * `--man1dir`
 626 * `--localedir`
 627
 628 An example is:
 629
 630 ```
 631 ./configure.sh --prefix=/usr --localedir /usr/share/nls
 632 make
 633 make install
 634 ```
 635
 636 They correspond to the environment variables `$PREFIX`, `$BINDIR`,
 637 `$DATAROOTDIR`, `$DATADIR`, `$MANDIR`, `$MAN1DIR`, and `$LOCALEDIR`,
 638 respectively.
 639
 640 ***WARNING***: If the option is given, the value of the corresponding
 641 environment variable is overridden.
 642
 643 ***WARNING***: If any long command-line options are used, the long form of all
 644 other command-line options must be used. Mixing long and short options is not
 645 supported.
 646
 647 ##### Manpages
 648
 649 To disable installing manpages, pass either the `-M` flag or the
 650 `--disable-man-pages` option to `configure.sh` as follows:
 651
 652 ```
 653 ./configure.sh -M
 654 ./configure.sh --disable-man-pages
 655 ```
 656
 657 Both commands are equivalent.
 658
 659 ##### Locales
 660
 661 By default, `bc` and `dc` do not install all locales, but only the enabled
 662 locales. If `DESTDIR` exists and is not empty, then they will install all of
 663 the locales that exist on the system. The `-l` flag or `--install-all-locales`
 664 option skips all of that and just installs all of the locales that `bc` and `dc`
 665 have, regardless. To enable that behavior, you can pass the `-l` flag or the
 666 `--install-all-locales` option to `configure.sh`, as follows:
 667
 668 ```
 669 ./configure.sh -l
 670 ./configure.sh --install-all-locales
 671 ```
 672
 673 Both commands are equivalent.
 674
 675 ### Optimization
 676
 677 The `configure.sh` script will accept an optimization level to pass to the
 678 compiler. Because `bc` is orders of magnitude faster with optimization, I
 679 ***highly*** recommend package and distro maintainers pass the highest
 680 optimization level available in `CC` to `configure.sh` with the `-O` flag or
 681 `--opt` option, as follows:
 682
 683 ```
 684 ./configure.sh -O3
 685 ./configure.sh --opt 3
 686 ```
 687
 688 Both commands are equivalent.
 689
 690 The build and install can then be run as normal:
 691
 692 ```
 693 make
 694 make install
 695 ```
 696
 697 As usual, `configure.sh` will also accept additional `CFLAGS` on the command
 698 line, so for SSE4 architectures, the following can add a bit more speed:
 699
 700 ```
 701 CFLAGS="-march=native -msse4" ./configure.sh -O3
 702 make
 703 make install
 704 ```
 705
 706 Building with link-time optimization (`-flto` in clang) can further increase the
 707 performance. I ***highly*** recommend doing so.
 708
 709 I do ***NOT*** recommend building with `-march=native`; doing so reduces this
 710 `bc`'s performance.
 711
 712 Manual stripping is not necessary; non-debug builds are automatically stripped
 713 in the link stage.
 714
 715 ### Debug Builds
 716
 717 Debug builds (which also disable optimization if no optimization level is given
 718 and if no extra `CFLAGS` are given) can be enabled with either the `-g` flag or
 719 the `--debug` option, as follows:
 720
 721 ```
 722 ./configure.sh -g
 723 ./configure.sh --debug
 724 ```
 725
 726 Both commands are equivalent.
 727
 728 The build and install can then be run as normal:
 729
 730 ```
 731 make
 732 make install
 733 ```
 734
 735 ### Stripping Binaries
 736
 737 By default, when `bc` and `dc` are not built in debug mode, the binaries are
 738 stripped. Stripping can be disabled with either the `-T` or the
 739 `--disable-strip` option, as follows:
 740
 741 ```
 742 ./configure.sh -T
 743 ./configure.sh --disable-strip
 744 ```
 745
 746 Both commands are equivalent.
 747
 748 The build and install can then be run as normal:
 749
 750 ```
 751 make
 752 make install
 753 ```
 754
 755 ### Build Type
 756
 757 `bc` and `dc` have 8 build types, affected by the [History][8], [NLS (Locale
 758 Support)][9], and [Extra Math][10] build options.
 759
 760 The build types are as follows:
 761
 762 * `A`: Nothing disabled.
 763 * `E`: Extra math disabled.
 764 * `H`: History disabled.
 765 * `N`: NLS disabled.
 766 * `EH`: Extra math and History disabled.
 767 * `EN`: Extra math and NLS disabled.
 768 * `HN`: History and NLS disabled.
 769 * `EHN`: Extra math, History, and NLS all disabled.
 770
 771 These build types correspond to the generated manuals in `manuals/bc` and
 772 `manuals/dc`.
 773
 774 ### Binary Size
 775
 776 When built with both calculators, all available features, and `-Os` using
 777 `clang` and `musl`, the executable is 140.4 kb (140,386 bytes) on `x86_64`. That
 778 isn't much for what is contained in the binary, but if necessary, it can be
 779 reduced.
 780
 781 The single largest user of space is the `bc` calculator. If just `dc` is needed,
 782 the size can be reduced to 107.6 kb (107,584 bytes).
 783
 784 The next largest user of space is history support. If that is not needed, size
 785 can be reduced (for a build with both calculators) to 119.9 kb (119,866 bytes).
 786
 787 There are several reasons that history is a bigger user of space than `dc`
 788 itself:
 789
 790 * `dc`'s lexer and parser are *tiny* compared to `bc`'s because `dc` code is
 791   almost already in the form that it is executed in, while `bc` has to not only
 792   adjust the form to be executable, it has to parse functions, loops, `if`
 793   statements, and other extra features.
 794 * `dc` does not have much extra code in the interpreter.
 795 * History has a lot of const data for supporting `UTF-8` terminals.
 796 * History pulls in a bunch of more code from the `libc`.
 797
 798 The next biggest user is extra math support. Without it, the size is reduced to
 799 124.0 kb (123,986 bytes) with history and 107.6 kb (107,560 bytes) without
 800 history.
 801
 802 The reasons why extra math support is bigger than `dc`, besides the fact that
 803 `dc` is small already, are:
 804
 805 * Extra math supports adds an extra math library that takes several kilobytes of
 806   constant data space.
 807 * Extra math support includes support for a pseudo-random number generator,
 808   including the code to convert a series of pseudo-random numbers into a number
 809   of arbitrary size.
 810 * Extra math support adds several operators.
 811
 812 The next biggest user is `dc`, so if just `bc` is needed, the size can be
 813 reduced to 128.1 kb (128,096 bytes) with history and extra math support, 107.6
 814 kb (107,576 bytes) without history and with extra math support, and 95.3 kb
 815 (95,272 bytes) without history and without extra math support.
 816
 817 *Note*: all of these binary sizes were compiled using `musl` `1.2.0` as the
 818 `libc`, making a fully static executable, with `clang` `9.0.1` (well,
 819 `musl-clang` using `clang` `9.0.1`) as the compiler and using `-Os`
 820 optimizations. These builds were done on an `x86_64` machine running Gentoo
 821 Linux.
 822
 823 ### Testing
 824
 825 The default test suite can be run with the following command:
 826
 827 ```
 828 make test
 829 ```
 830
 831 To test `bc` only, run the following command:
 832
 833 ```
 834 make test_bc
 835 ```
 836
 837 To test `dc` only, run the following command:
 838
 839 ```
 840 make test_dc
 841 ```
 842
 843 This `bc`, if built, assumes a working, GNU-compatible `bc`, installed on the
 844 system and in the `PATH`, to generate some tests, unless the `-G` flag or
 845 `--disable-generated-tests` option is given to `configure.sh`, as follows:
 846
 847 ```
 848 ./configure.sh -G
 849 ./configure.sh --disable-generated-tests
 850 ```
 851
 852 After running `configure.sh`, build and run tests as follows:
 853
 854 ```
 855 make
 856 make test
 857 ```
 858
 859 This `dc` also assumes a working, GNU-compatible `dc`, installed on the system
 860 and in the `PATH`, to generate some tests, unless one of the above options is
 861 given to `configure.sh`.
 862
 863 To generate test coverage, pass the `-c` flag or the `--coverage` option to
 864 `configure.sh` as follows:
 865
 866 ```
 867 ./configure.sh -c
 868 ./configure.sh --coverage
 869 ```
 870
 871 Both commands are equivalent.
 872
 873 ***WARNING***: Both `bc` and `dc` must be built for test coverage. Otherwise,
 874 `configure.sh` will give an error.
 875
 876 [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
 877 [2]: https://www.gnu.org/software/bc/
 878 [3]: https://www.musl-libc.org/
 879 [4]: #build-environment-variables
 880 [5]: #build-options
 881 [6]: #cross-compiling
 882 [7]: #build-type
 883 [8]: #history
 884 [9]: #nls-locale-support
 885 [10]: #extra-math
 886 [11]: #settings