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