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