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