manuals/build.md

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