contrib/bc/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 ### `INCLUDEDIR`
 168
 169 The directory to install header files in.
 170
 171 Can be overridden by passing the `--includedir` option to `configure.sh`.
 172
 173 Defaults to `$PREFIX/include`.
 174
 175 ### `LIBDIR`
 176
 177 The directory to install libraries in.
 178
 179 Can be overridden by passing the `--libdir` option to `configure.sh`.
 180
 181 Defaults to `$PREFIX/lib`.
 182
 183 ### `DATAROOTDIR`
 184
 185 The root directory to install data files in.
 186
 187 Can be overridden by passing the `--datarootdir` option to `configure.sh`.
 188
 189 Defaults to `$PREFIX/share`.
 190
 191 ### `DATADIR`
 192
 193 The directory to install data files in.
 194
 195 Can be overridden by passing the `--datadir` option to `configure.sh`.
 196
 197 Defaults to `$DATAROOTDIR`.
 198
 199 ### `MANDIR`
 200
 201 The directory to install manpages in.
 202
 203 Can be overridden by passing the `--mandir` option to `configure.sh`.
 204
 205 Defaults to `$DATADIR/man`
 206
 207 ### `MAN1DIR`
 208
 209 The directory to install Section 1 manpages in. Because both `bc` and `dc` are
 210 Section 1 commands, this is the only relevant section directory.
 211
 212 Can be overridden by passing the `--man1dir` option to `configure.sh`.
 213
 214 Defaults to `$MANDIR/man1`.
 215
 216 ### `LOCALEDIR`
 217
 218 The directory to install locales in.
 219
 220 Can be overridden by passing the `--localedir` option to `configure.sh`.
 221
 222 Defaults to `$DATAROOTDIR/locale`.
 223
 224 ### `EXECSUFFIX`
 225
 226 The suffix to append onto the executable names *when installing*. This is for
 227 packagers and distro maintainers who want this `bc` as an option, but do not
 228 want to replace the default `bc`.
 229
 230 Defaults to empty.
 231
 232 ### `EXECPREFIX`
 233
 234 The prefix to append onto the executable names *when building and installing*.
 235 This is for packagers and distro maintainers who want this `bc` as an option,
 236 but do not want to replace the default `bc`.
 237
 238 Defaults to empty.
 239
 240 ### `LONG_BIT`
 241
 242 The number of bits in a C `long` type. This is mostly for the embedded space.
 243
 244 This `bc` uses `long`s internally for overflow checking. In C99, a `long` is
 245 required to be 32 bits. For this reason, on 8-bit and 16-bit microcontrollers,
 246 the generated code to do math with `long` types may be inefficient.
 247
 248 For most normal desktop systems, setting this is unnecessary, except that 32-bit
 249 platforms with 64-bit longs may want to set it to `32`.
 250
 251 Defaults to the default value of `LONG_BIT` for the target platform. For
 252 compliance with the `bc` spec, the minimum allowed value is `32`.
 253
 254 It 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
 259 Whether to use `gen/strgen.c`, instead of `gen/strgen.sh`, to produce the C
 260 files 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
 263 machine since `gen/strgen.sh` is a POSIX shell script. However, `gen/lib2.bc` is
 264 perilously close to 4095 characters, the max supported length of a string
 265 literal in C99 (and it could be added to in the future), and `gen/strgen.sh`
 266 generates a string literal instead of an array, as `gen/strgen.c` does. For most
 267 production-ready compilers, this limit probably is not enforced, but it could
 268 be. Both options are still available for this reason.
 269
 270 If you are sure your compiler does not have the limit and do not want to compile
 271 and run a binary on the host machine, set this variable to "0". Any other value,
 272 or a non-existent value, will cause the build system to compile and run
 273 `gen/strgen.c`.
 274
 275 Default is "".
 276
 277 ### `GEN_EMU`
 278
 279 The emulator to run bootstrap binaries under. This is only if the binaries
 280 produced by `HOSTCC` (or `HOST_CC`) need to be run under an emulator to work.
 281
 282 Defaults to empty.
 283
 284 <a name="build-options"/>
 285
 286 ## Build Options
 287
 288 This `bc` comes with several build options, all of which are enabled by default.
 289
 290 All options can be used with each other, with a few exceptions that will be
 291 noted below.
 292
 293 **NOTE**: All long options with mandatory argumenst accept either one of the
 294 following forms:
 295
 296 ```
 297 --option arg
 298 --option=arg
 299 ```
 300
 301 ### Library
 302
 303 To build the math library, use the following commands for the configure step:
 304
 305 ```
 306 ./configure.sh -a
 307 ./configure.sh --library
 308 ```
 309
 310 Both commands are equivalent.
 311
 312 When the library is built, history, prompt, and locales are disabled, and the
 313 functionality 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
 316 To build an optimized version of the library, users can pass optimization
 317 options to `configure.sh` or include them in `CFLAGS`.
 318
 319 The library API can be found in `manuals/bcl.3.md` or `man bcl` once the library
 320 is installed.
 321
 322 The library is built as `bin/libbcl.a`.
 323
 324 ### `bc` Only
 325
 326 To build `bc` only (no `dc`), use any one of the following commands for the
 327 configure step:
 328
 329 ```
 330 ./configure.sh -b
 331 ./configure.sh --bc-only
 332 ./configure.sh -D
 333 ./configure.sh --disable-dc
 334 ```
 335
 336 Those commands are all equivalent.
 337
 338 ***Warning***: It is an error to use those options if `bc` has also been
 339 disabled (see below).
 340
 341 ### `dc` Only
 342
 343 To build `dc` only (no `bc`), use either one of the following commands for the
 344 configure step:
 345
 346 ```
 347 ./configure.sh -d
 348 ./configure.sh --dc-only
 349 ./configure.sh -B
 350 ./configure.sh --disable-bc
 351 ```
 352
 353 Those commands are all equivalent.
 354
 355 ***Warning***: It is an error to use those options if `dc` has also been
 356 disabled (see above).
 357
 358 <a name="build-history"/>
 359
 360 ### History
 361
 362 To disable signal handling, pass either the `-H` flag or the `--disable-history`
 363 option to `configure.sh`, as follows:
 364
 365 ```
 366 ./configure.sh -H
 367 ./configure.sh --disable-history
 368 ```
 369
 370 Both commands are equivalent.
 371
 372 History is automatically disabled when building for Windows or on another
 373 platform 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
 376 completely portable. If the `bc` does not work on your platform, your first step
 377 should be to retry with history disabled.
 378
 379 ### NLS (Locale Support)
 380
 381 To 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
 389 Both commands are equivalent.
 390
 391 NLS (locale support) is automatically disabled when building for Windows or on
 392 another platform that does not support the POSIX locale API or utilities.
 393
 394 ### Prompt
 395
 396 By default, `bc` and `dc` print a prompt when in interactive mode. They both
 397 have the command-line option `-P`/`--no-prompt`, which turns that off, but it
 398 can 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
 406 Both commands are equivalent.
 407
 408 ### Locales
 409
 410 By default, `bc` and `dc` do not install all locales, but only the enabled
 411 locales. If `DESTDIR` exists and is not empty, then they will install all of
 412 the locales that exist on the system. The `-l` flag or `--install-all-locales`
 413 option skips all of that and just installs all of the locales that `bc` and `dc`
 414 have, 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
 422 Both commands are equivalent.
 423
 424 ### Extra Math
 425
 426 This `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
 436 There is no assignment version of `$` because it is a unary operator.
 437
 438 The assignment versions of the above operators are not available in `dc`, but
 439 the others are, as the operators `$`, `@`, `H`, and `h`, respectively.
 440
 441 In addition, this `bc` has the option of outputting in scientific notation or
 442 engineering notation. It can also take input in scientific or engineering
 443 notation. On top of that, it has a pseudo-random number generator. (See the
 444 full manual for more details.)
 445
 446 Extra operators, scientific notation, engineering notation, and the
 447 pseudo-random number generator can be disabled by passing either the `-E` flag
 448 or the `--disable-extra-math` option to `configure.sh`, as follows:
 449
 450 ```
 451 ./configure.sh -E
 452 ./configure.sh --disable-extra-math
 453 ```
 454
 455 Both commands are equivalent.
 456
 457 This `bc` also has a larger library that is only enabled if extra operators and
 458 the pseudo-random number generator are. More information about the functions can
 459 be found in the Extended Library section of the full manual.
 460
 461 ### Manpages
 462
 463 To 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
 471 Both commands are equivalent.
 472
 473 ### Karatsuba Length
 474
 475 The Karatsuba length is the point at which `bc` and `dc` switch from Karatsuba
 476 multiplication to brute force, `O(n^2)` multiplication. It can be set by passing
 477 the `-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
 484 Both commands are equivalent.
 485
 486 Default is `64`.
 487
 488 ***WARNING***: The Karatsuba Length must be a **integer** greater than or equal
 489 to `16` (to prevent stack overflow). If it is not, `configure.sh` will give an
 490 error.
 491
 492 ### Install Options
 493
 494 The 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
 504 An example is:
 505
 506 ```
 507 ./configure.sh --prefix=/usr --localedir /usr/share/nls
 508 make
 509 make install
 510 ```
 511
 512 They correspond to the environment variables `$PREFIX`, `$BINDIR`,
 513 `$DATAROOTDIR`, `$DATADIR`, `$MANDIR`, `$MAN1DIR`, and `$LOCALEDIR`,
 514 respectively.
 515
 516 ***WARNING***: If the option is given, the value of the corresponding
 517 environment variable is overridden.
 518
 519 ***WARNING***: If any long command-line options are used, the long form of all
 520 other command-line options must be used. Mixing long and short options is not
 521 supported.
 522
 523 ## Optimization
 524
 525 The `configure.sh` script will accept an optimization level to pass to the
 526 compiler. Because `bc` is orders of magnitude faster with optimization, I
 527 ***highly*** recommend package and distro maintainers pass the highest
 528 optimization 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
 536 Both commands are equivalent.
 537
 538 The build and install can then be run as normal:
 539
 540 ```
 541 make
 542 make install
 543 ```
 544
 545 As usual, `configure.sh` will also accept additional `CFLAGS` on the command
 546 line, so for SSE4 architectures, the following can add a bit more speed:
 547
 548 ```
 549 CFLAGS="-march=native -msse4" ./configure.sh -O3
 550 make
 551 make install
 552 ```
 553
 554 Building with link-time optimization (`-flto` in clang) can further increase the
 555 performance. I ***highly*** recommend doing so.
 556
 557 I do **NOT*** recommend building with `-march=native`; doing so reduces this
 558 `bc`'s performance.
 559
 560 Manual stripping is not necessary; non-debug builds are automatically stripped
 561 in the link stage.
 562
 563 ## Debug Builds
 564
 565 Debug builds (which also disable optimization if no optimization level is given
 566 and if no extra `CFLAGS` are given) can be enabled with either the `-g` flag or
 567 the `--debug` option, as follows:
 568
 569 ```
 570 ./configure.sh -g
 571 ./configure.sh --debug
 572 ```
 573
 574 Both commands are equivalent.
 575
 576 The build and install can then be run as normal:
 577
 578 ```
 579 make
 580 make install
 581 ```
 582
 583 ## Stripping Binaries
 584
 585 By default, when `bc` and `dc` are not built in debug mode, the binaries are
 586 stripped. 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
 594 Both commands are equivalent.
 595
 596 The build and install can then be run as normal:
 597
 598 ```
 599 make
 600 make install
 601 ```
 602
 603 ## Binary Size
 604
 605 When 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
 607 isn't much for what is contained in the binary, but if necessary, it can be
 608 reduced.
 609
 610 The single largest user of space is the `bc` calculator. If just `dc` is needed,
 611 the size can be reduced to 107.6 kb (107,584 bytes).
 612
 613 The next largest user of space is history support. If that is not needed, size
 614 can be reduced (for a build with both calculators) to 119.9 kb (119,866 bytes).
 615
 616 There are several reasons that history is a bigger user of space than `dc`
 617 itself:
 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
 627 The next biggest user is extra math support. Without it, the size is reduced to
 628 124.0 kb (123,986 bytes) with history and 107.6 kb (107,560 bytes) without
 629 history.
 630
 631 The 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
 641 The next biggest user is `dc`, so if just `bc` is needed, the size can be
 642 reduced to 128.1 kb (128,096 bytes) with history and extra math support, 107.6
 643 kb (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`
 649 optimizations. These builds were done on an `x86_64` machine running Gentoo
 650 Linux.
 651
 652 ## Testing
 653
 654 The default test suite can be run with the following command:
 655
 656 ```
 657 make test
 658 ```
 659
 660 To test `bc` only, run the following command:
 661
 662 ```
 663 make test_bc
 664 ```
 665
 666 To test `dc` only, run the following command:
 667
 668 ```
 669 make test_dc
 670 ```
 671
 672 This `bc`, if built, assumes a working, GNU-compatible `bc`, installed on the
 673 system 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
 681 After running `configure.sh`, build and run tests as follows:
 682
 683 ```
 684 make
 685 make test
 686 ```
 687
 688 This `dc` also assumes a working, GNU-compatible `dc`, installed on the system
 689 and in the `PATH`, to generate some tests, unless one of the above options is
 690 given to `configure.sh`.
 691
 692 To 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
 700 Both 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