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