1# Build 2 3This `bc` attempts to be as portable as possible. It can be built on any 4POSIX-compliant system. 5 6To accomplish that, a POSIX-compatible, custom `configure.sh` script is used to 7select build options, compiler, and compiler flags and generate a `Makefile`. 8 9The general form of configuring, building, and installing this `bc` is as 10follows: 11 12``` 13[ENVIRONMENT_VARIABLE=<value>...] ./configure.sh [build_options...] 14make 15make install 16``` 17 18To get all of the options, including any useful environment variables, use 19either 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 27long, it does not support handling both at the same time. Use only one type. 28 29To learn the available `make` targets run the following command after running 30the `configure.sh` script: 31 32``` 33make help 34``` 35 36See [Build Environment Variables][4] for a more detailed description of all 37accepted environment variables and [Build Options][5] for more detail about all 38accepted build options. 39 40## Windows 41 42For releases, Windows builds of `bc`, `dc`, and `bcl` are available for download 43from <https://git.gavinhoward.com/gavin/bc> and GitHub. 44 45However, if you wish to build it yourself, this `bc` can be built using Visual 46Studio or MSBuild. 47 48Unfortunately, only one build configuration (besides Debug or Release) is 49supported: extra math and history enabled, NLS (locale support) disabled, with 50both 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 53The library can also be built on Windows. 54 55### Visual Studio 56 57In Visual Studio, open up the solution file (`bc.sln` for `bc`, or `bcl.sln` for 58the library), select the desired configuration, and build. 59 60### MSBuild 61 62To build with MSBuild, first, *be sure that you are using the MSBuild that comes 63with Visual Studio*. 64 65To build `bc`, run the following from the root directory: 66 67``` 68msbuild -property:Configuration=<config> vs/bc.sln 69``` 70 71where `<config>` is either one of `Debug` or `Release`. 72 73To build the library, run the following from the root directory: 74 75``` 76msbuild -property:Configuration=<config> vs/bcl.sln 77``` 78 79where `<config>` is either one of `Debug`, `ReleaseMD`, or `ReleaseMT`. 80 81## POSIX-Compatible Systems 82 83Building `bc`, `dc`, and `bcl` (the library) is more complex than on Windows 84because many build options are supported. 85 86### Out-of-Source Builds 87 88Out-of-source builds are done by calling `configure.sh` from the directory where 89the build will happen. The `Makefile` is generated into that directory, and the 90build can happen normally from there. 91 92For example, if the source is in `bc`, the build should happen in `build`, then 93call `configure.sh` and `make` like so: 94 95``` 96../bc/configure.sh 97make 98``` 99 100***WARNING***: The path to `configure.sh` from the build directory must not have 101spaces because `make` does not support target names with spaces. 102 103### Cross Compiling 104 105To cross-compile this `bc`, an appropriate compiler must be present and assigned 106to the environment variable `HOSTCC` or `HOST_CC` (the two are equivalent, 107though `HOSTCC` is prioritized). This is in order to bootstrap core file(s), if 108the architectures are not compatible (i.e., unlike i686 on x86_64). Thus, the 109approach is: 110 111``` 112HOSTCC="/path/to/native/compiler" ./configure.sh 113make 114make 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 121prioritized over `HOST_CFLAGS`. If neither are present, `HOSTCC` (or `HOST_CC`) 122uses `CFLAGS` (see [Build Environment Variables][4] for more details). 123 124It is expected that `CC` produces code for the target system and `HOSTCC` 125produces code for the host system. See [Build Environment Variables][4] for more 126details. 127 128If an emulator is necessary to run the bootstrap binaries, it can be set with 129the environment variable `GEN_EMU`. 130 131### Build Environment Variables 132 133This `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 138put into the generated Makefile. 139 140More detail on what those environment variables do can be found in the following 141sections. 142 143#### `CC` 144 145C compiler for the target system. `CC` must be compatible with POSIX `c99` 146behavior and options. However, **I encourage users to use any C99 or C11 147compatible compiler they wish.** 148 149If there is a space in the basename of the compiler, the items after the first 150space are assumed to be compiler flags, and in that case, the flags are 151automatically moved into CFLAGS. 152 153Defaults to `c99`. 154 155#### `HOSTCC` or `HOST_CC` 156 157C compiler for the host system, used only in [cross compiling][6]. Must be 158compatible with POSIX `c99` behavior and options. 159 160If there is a space in the basename of the compiler, the items after the first 161space are assumed to be compiler flags, and in that case, the flags are 162automatically moved into HOSTCFLAGS. 163 164Defaults to `$CC`. 165 166#### `CFLAGS` 167 168Command-line flags that will be passed verbatim to `CC`. 169 170Defaults to empty. 171 172#### `HOSTCFLAGS` or `HOST_CFLAGS` 173 174Command-line flags that will be passed verbatim to `HOSTCC` or `HOST_CC`. 175 176Defaults to `$CFLAGS`. 177 178#### `CPPFLAGS` 179 180Command-line flags for the C preprocessor. These are also passed verbatim to 181both compilers (`CC` and `HOSTCC`); they are supported just for legacy reasons. 182 183Defaults to empty. 184 185#### `LDFLAGS` 186 187Command-line flags for the linker. These are also passed verbatim to both 188compilers (`CC` and `HOSTCC`); they are supported just for legacy reasons. 189 190Defaults to empty. 191 192#### `LDLIBS` 193 194Libraries 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 196with different C standard libraries (like [musl][3]). 197 198Defaults to empty. 199 200#### `PREFIX` 201 202The prefix to install to. 203 204Can be overridden by passing the `--prefix` option to `configure.sh`. 205 206Defaults to `/usr/local`. 207 208***WARNING***: Locales ignore the prefix because they *must* be installed at a 209fixed location to work at all. If you do not want that to happen, you must 210disable locales (NLS) completely. 211 212#### `DESTDIR` 213 214Path to prepend onto `PREFIX`. This is mostly for distro and package 215maintainers. 216 217This can be passed either to `configure.sh` or `make install`. If it is passed 218to both, the one given to `configure.sh` takes precedence. 219 220Defaults to empty. 221 222#### `BINDIR` 223 224The directory to install binaries in. 225 226Can be overridden by passing the `--bindir` option to `configure.sh`. 227 228Defaults to `$PREFIX/bin`. 229 230#### `INCLUDEDIR` 231 232The directory to install header files in. 233 234Can be overridden by passing the `--includedir` option to `configure.sh`. 235 236Defaults to `$PREFIX/include`. 237 238#### `LIBDIR` 239 240The directory to install libraries in. 241 242Can be overridden by passing the `--libdir` option to `configure.sh`. 243 244Defaults to `$PREFIX/lib`. 245 246#### `DATAROOTDIR` 247 248The root directory to install data files in. 249 250Can be overridden by passing the `--datarootdir` option to `configure.sh`. 251 252Defaults to `$PREFIX/share`. 253 254#### `DATADIR` 255 256The directory to install data files in. 257 258Can be overridden by passing the `--datadir` option to `configure.sh`. 259 260Defaults to `$DATAROOTDIR`. 261 262#### `MANDIR` 263 264The directory to install manpages in. 265 266Can be overridden by passing the `--mandir` option to `configure.sh`. 267 268Defaults to `$DATADIR/man` 269 270#### `MAN1DIR` 271 272The directory to install Section 1 manpages in. Because both `bc` and `dc` are 273Section 1 commands, this is the only relevant section directory. 274 275Can be overridden by passing the `--man1dir` option to `configure.sh`. 276 277Defaults to `$MANDIR/man1`. 278 279#### `MAN3DIR` 280 281The directory to install Section 3 manpages in. 282 283Can be overridden by passing the `--man3dir` option to `configure.sh`. 284 285Defaults to `$MANDIR/man3`. 286 287#### `EXECSUFFIX` 288 289The suffix to append onto the executable names *when installing*. This is for 290packagers and distro maintainers who want this `bc` as an option, but do not 291want to replace the default `bc`. 292 293Defaults to empty. 294 295#### `EXECPREFIX` 296 297The prefix to append onto the executable names *when building and installing*. 298This is for packagers and distro maintainers who want this `bc` as an option, 299but do not want to replace the default `bc`. 300 301Defaults to empty. 302 303#### `LONG_BIT` 304 305The number of bits in a C `long` type. This is mostly for the embedded space. 306 307This `bc` uses `long`s internally for overflow checking. In C99, a `long` is 308required to be 32 bits. For this reason, on 8-bit and 16-bit microcontrollers, 309the generated code to do math with `long` types may be inefficient. 310 311For most normal desktop systems, setting this is unnecessary, except that 32-bit 312platforms with 64-bit longs may want to set it to `32`. 313 314Defaults to the default value of `LONG_BIT` for the target platform. For 315compliance with the `bc` spec, the minimum allowed value is `32`. 316 317It 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 322Whether to use `gen/strgen.c`, instead of `gen/strgen.sh`, to produce the C 323files 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 326machine since `gen/strgen.sh` is a POSIX shell script. However, `gen/lib2.bc` is 327perilously close to 4095 characters, the max supported length of a string 328literal in C99 (and it could be added to in the future), and `gen/strgen.sh` 329generates a string literal instead of an array, as `gen/strgen.c` does. For most 330production-ready compilers, this limit probably is not enforced, but it could 331be. Both options are still available for this reason. 332 333If you are sure your compiler does not have the limit and do not want to compile 334and run a binary on the host machine, set this variable to "0". Any other value, 335or a non-existent value, will cause the build system to compile and run 336`gen/strgen.c`. 337 338Default is "". 339 340#### `GEN_EMU` 341 342The emulator to run bootstrap binaries under. This is only if the binaries 343produced by `HOSTCC` (or `HOST_CC`) need to be run under an emulator to work. 344 345Defaults to empty. 346 347### Build Options 348 349This `bc` comes with several build options, all of which are enabled by default. 350 351All options can be used with each other, with a few exceptions that will be 352noted below. 353 354**NOTE**: All long options with mandatory argumenst accept either one of the 355following forms: 356 357``` 358--option arg 359--option=arg 360``` 361 362#### Predefined Builds 363 364To quickly get a release build of a `bc` and `dc` that is (by default) 365compatible with the BSD `bc` and `dc`, use the `-p` or `--predefined-build-type` 366options: 367 368``` 369./configure.sh -pBSD 370./configure.sh --predefined-build-type=BSD 371``` 372 373Both commands are equivalent. 374 375To quickly get a release build of a `bc` and `dc` that is (by default) 376compatible with the GNU `bc` and `dc`, use the `-p` or `--predefined-build-type` 377options: 378 379``` 380./configure.sh -pGNU 381./configure.sh --predefined-build-type=GNU 382``` 383 384Both commands are equivalent. 385 386#### Library 387 388To build the math library, use the following commands for the configure step: 389 390``` 391./configure.sh -a 392./configure.sh --library 393``` 394 395Both commands are equivalent. 396 397When the library is built, history and locales are disabled, and the 398functionality 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 401To build an optimized version of the library, users can pass optimization 402options to `configure.sh` or include them in `CFLAGS`. 403 404The library API can be found in `manuals/bcl.3.md` or `man bcl` once the library 405is installed. 406 407The library is built as `bin/libbcl.a`. 408 409#### `bc` Only 410 411To build `bc` only (no `dc`), use any one of the following commands for the 412configure step: 413 414``` 415./configure.sh -b 416./configure.sh --bc-only 417./configure.sh -D 418./configure.sh --disable-dc 419``` 420 421Those commands are all equivalent. 422 423***Warning***: It is an error to use those options if `bc` has also been 424disabled (see below). 425 426#### `dc` Only 427 428To build `dc` only (no `bc`), use either one of the following commands for the 429configure step: 430 431``` 432./configure.sh -d 433./configure.sh --dc-only 434./configure.sh -B 435./configure.sh --disable-bc 436``` 437 438Those commands are all equivalent. 439 440***Warning***: It is an error to use those options if `dc` has also been 441disabled (see above). 442 443#### History 444 445To disable hisory, pass either the `-H` flag or the `--disable-history` option 446to `configure.sh`, as follows: 447 448``` 449./configure.sh -H 450./configure.sh --disable-history 451``` 452 453Both commands are equivalent. 454 455***WARNING***: Of all of the code in the `bc`, this is the only code that is not 456completely portable. If the `bc` does not work on your platform, your first step 457should be to retry with history disabled. 458 459This option affects the [build type][7]. 460 461##### Editline 462 463History support can be provided by editline, in order to implement `vi`-like 464keybindings and other features. 465 466To enable editline support, pass either the `-e` flag or the `--enable-editline` 467option to `configure.sh`, as follows: 468 469``` 470./configure.sh -e 471./configure.sh --enable-editline 472``` 473 474Both commands are equivalent. 475 476This is ignored if history is disabled. 477 478This option is only used if it is after any other `-e`/`--enable-editline` 479options, any `-r`/`--enable-readline` options, and any 480`-i`/`--enable-internal-history` options. 481 482##### Readline 483 484History support can be provided by readline, in order to implement `vi`-like 485keybindings and other features. 486 487To enable readline support, pass either the `-r` flag or the `--enable-readline` 488option to `configure.sh`, as follows: 489 490``` 491./configure.sh -r 492./configure.sh --enable-readline 493``` 494 495Both commands are equivalent. 496 497This is ignored if history is disabled. 498 499This option is only used if it is after any other `-r`/`--enable-readline` 500options, any `-e`/`--enable-editline` options, and any 501`-i`/`--enable-internal-history` options. 502 503##### Internal History 504 505History support is also available as an internal implementation with no 506dependencies. This is the default if editline and readline are not selected. 507 508However, if `-p` option is used, then this option can be useful for selecting 509the internal history regardless of what the predefined build has. 510 511To 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 519This option is only used if it is after any other 520`-i`/`--enable-internal-history` options, any `-e`/`--enable-editline` options, 521and any `-r`/`--enable-readline` options. 522 523#### NLS (Locale Support) 524 525To 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 533Both commands are equivalent. 534 535NLS (locale support) is automatically disabled when building for Windows or on 536another platform that does not support the POSIX locale API or utilities. 537 538This option affects the [build type][7]. 539 540***WARNING***: Locales ignore the prefix because they *must* be installed at a 541fixed location to work at all. If you do not want that to happen, you must 542disable locales (NLS) completely. 543 544#### Extra Math 545 546This `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 556There is no assignment version of `$` because it is a unary operator. 557 558The assignment versions of the above operators are not available in `dc`, but 559the others are, as the operators `$`, `@`, `H`, and `h`, respectively. 560 561In addition, this `bc` has the option of outputting in scientific notation or 562engineering notation. It can also take input in scientific or engineering 563notation. On top of that, it has a pseudo-random number generator. (See the 564full manual for more details.) 565 566Extra operators, scientific notation, engineering notation, and the 567pseudo-random number generator can be disabled by passing either the `-E` flag 568or the `--disable-extra-math` option to `configure.sh`, as follows: 569 570``` 571./configure.sh -E 572./configure.sh --disable-extra-math 573``` 574 575Both commands are equivalent. 576 577This `bc` also has a larger library that is only enabled if extra operators and 578the pseudo-random number generator are. More information about the functions can 579be found in the Extended Library section of the full manual. 580 581This option affects the [build type][7]. 582 583#### Karatsuba Length 584 585The Karatsuba length is the point at which `bc` and `dc` switch from Karatsuba 586multiplication to brute force, `O(n^2)` multiplication. It can be set by passing 587the `-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 594Both commands are equivalent. 595 596Default is `32`. 597 598***WARNING***: The Karatsuba Length must be a **integer** greater than or equal 599to `16` (to prevent stack overflow). If it is not, `configure.sh` will give an 600error. 601 602#### Settings 603 604This `bc` and `dc` have a few settings to override default behavior. 605 606The defaults for these settings can be set by package maintainers, and the 607settings themselves can be overriden by users. 608 609To 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 617Both commands are equivalent. 618 619To 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 627Both commands are equivalent. 628 629Users can override the default settings set by packagers with environment 630variables. If the environment variable has an integer, then the setting is 631turned **on** for a non-zero integer, and **off** for zero. 632 633The table of the available settings, along with their defaults and the 634environment 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 698These settings are not meant to be changed on a whim. They are meant to ensure 699that this bc and dc will conform to the expectations of the user on each 700platform. 701 702#### Install Options 703 704The 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 714An example is: 715 716``` 717./configure.sh --prefix=/usr 718make 719make install 720``` 721 722They 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 726fixed location to work at all. If you do not want that to happen, you must 727disable locales (NLS) completely. 728 729***WARNING***: If the option is given, the value of the corresponding 730environment variable is overridden. 731 732***WARNING***: If any long command-line options are used, the long form of all 733other command-line options must be used. Mixing long and short options is not 734supported. 735 736##### Manpages 737 738To 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 746Both commands are equivalent. 747 748##### Locales 749 750By default, `bc` and `dc` do not install all locales, but only the enabled 751locales. If `DESTDIR` exists and is not empty, then they will install all of 752the locales that exist on the system. The `-l` flag or `--install-all-locales` 753option skips all of that and just installs all of the locales that `bc` and `dc` 754have, 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 762Both commands are equivalent. 763 764***WARNING***: Locales ignore the prefix because they *must* be installed at a 765fixed location to work at all. If you do not want that to happen, you must 766disable locales (NLS) completely. 767 768### Optimization 769 770The `configure.sh` script will accept an optimization level to pass to the 771compiler. Because `bc` is orders of magnitude faster with optimization, I 772***highly*** recommend package and distro maintainers pass the highest 773optimization 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 781Both commands are equivalent. 782 783The build and install can then be run as normal: 784 785``` 786make 787make install 788``` 789 790As usual, `configure.sh` will also accept additional `CFLAGS` on the command 791line, so for SSE4 architectures, the following can add a bit more speed: 792 793``` 794CFLAGS="-march=native -msse4" ./configure.sh -O3 795make 796make install 797``` 798 799Building with link-time optimization (`-flto` in clang) can further increase the 800performance. I ***highly*** recommend doing so. 801 802I do ***NOT*** recommend building with `-march=native`; doing so reduces this 803`bc`'s performance. 804 805Manual stripping is not necessary; non-debug builds are automatically stripped 806in the link stage. 807 808### Debug Builds 809 810Debug builds (which also disable optimization if no optimization level is given 811and if no extra `CFLAGS` are given) can be enabled with either the `-g` flag or 812the `--debug` option, as follows: 813 814``` 815./configure.sh -g 816./configure.sh --debug 817``` 818 819Both commands are equivalent. 820 821The build and install can then be run as normal: 822 823``` 824make 825make install 826``` 827 828### Stripping Binaries 829 830By default, when `bc` and `dc` are not built in debug mode, the binaries are 831stripped. 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 839Both commands are equivalent. 840 841The build and install can then be run as normal: 842 843``` 844make 845make install 846``` 847 848### Build Type 849 850`bc` and `dc` have 8 build types, affected by the [History][8], [NLS (Locale 851Support)][9], and [Extra Math][10] build options. 852 853The 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 864These build types correspond to the generated manuals in `manuals/bc` and 865`manuals/dc`. 866 867### Binary Size 868 869When 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 871isn't much for what is contained in the binary, but if necessary, it can be 872reduced. 873 874The single largest user of space is the `bc` calculator. If just `dc` is needed, 875the size can be reduced to 107.6 kb (107,584 bytes). 876 877The next largest user of space is history support. If that is not needed, size 878can be reduced (for a build with both calculators) to 119.9 kb (119,866 bytes). 879 880There are several reasons that history is a bigger user of space than `dc` 881itself: 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 891The next biggest user is extra math support. Without it, the size is reduced to 892124.0 kb (123,986 bytes) with history and 107.6 kb (107,560 bytes) without 893history. 894 895The 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 905The next biggest user is `dc`, so if just `bc` is needed, the size can be 906reduced to 128.1 kb (128,096 bytes) with history and extra math support, 107.6 907kb (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` 913optimizations. These builds were done on an `x86_64` machine running Gentoo 914Linux. 915 916### Testing 917 918The default test suite can be run with the following command: 919 920``` 921make test 922``` 923 924To test `bc` only, run the following command: 925 926``` 927make test_bc 928``` 929 930To test `dc` only, run the following command: 931 932``` 933make test_dc 934``` 935 936This `bc`, if built, assumes a working, GNU-compatible `bc`, installed on the 937system 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 945After running `configure.sh`, build and run tests as follows: 946 947``` 948make 949make test 950``` 951 952This `dc` also assumes a working, GNU-compatible `dc`, installed on the system 953and in the `PATH`, to generate some tests, unless one of the above options is 954given to `configure.sh`. 955 956To 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 964Both 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 971Some 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 973Linux, these tests are usually fine, but on FreeBSD, they are usually a problem. 974 975To 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 983Both 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 996