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