xref: /freebsd/contrib/bc/manuals/build.md (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
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### Library
286
287To build the math library, use the following commands for the configure step:
288
289```
290./configure.sh -a
291./configure.sh --library
292```
293
294Both commands are equivalent.
295
296When the library is built, history, prompt, and locales are disabled, and the
297functionality 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
300To build an optimized version of the library, users can pass optimization
301options to `configure.sh` or include them in `CFLAGS`.
302
303The library API can be found in `manuals/bcl.3.md` or `man bcl` once the library
304is installed.
305
306The library is built as `bin/libbcl.a`.
307
308### `bc` Only
309
310To build `bc` only (no `dc`), use any one of the following commands for the
311configure step:
312
313```
314./configure.sh -b
315./configure.sh --bc-only
316./configure.sh -D
317./configure.sh --disable-dc
318```
319
320Those commands are all equivalent.
321
322***Warning***: It is an error to use those options if `bc` has also been
323disabled (see below).
324
325### `dc` Only
326
327To build `dc` only (no `bc`), use either one of the following commands for the
328configure step:
329
330```
331./configure.sh -d
332./configure.sh --dc-only
333./configure.sh -B
334./configure.sh --disable-bc
335```
336
337Those commands are all equivalent.
338
339***Warning***: It is an error to use those options if `dc` has also been
340disabled (see above).
341
342<a name="build-history"/>
343
344### History
345
346To disable signal handling, pass either the `-H` flag or the `--disable-history`
347option to `configure.sh`, as follows:
348
349```
350./configure.sh -H
351./configure.sh --disable-history
352```
353
354Both commands are equivalent.
355
356History is automatically disabled when building for Windows or on another
357platform 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
360completely portable. If the `bc` does not work on your platform, your first step
361should be to retry with history disabled.
362
363### NLS (Locale Support)
364
365To 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
373Both commands are equivalent.
374
375NLS (locale support) is automatically disabled when building for Windows or on
376another platform that does not support the POSIX locale API or utilities.
377
378### Prompt
379
380By default, `bc` and `dc` print a prompt when in interactive mode. They both
381have the command-line option `-P`/`--no-prompt`, which turns that off, but it
382can 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
390Both commands are equivalent.
391
392### Locales
393
394By default, `bc` and `dc` do not install all locales, but only the enabled
395locales. If `DESTDIR` exists and is not empty, then they will install all of
396the locales that exist on the system. The `-l` flag or `--install-all-locales`
397option skips all of that and just installs all of the locales that `bc` and `dc`
398have, 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
406Both commands are equivalent.
407
408### Extra Math
409
410This `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
420There is no assignment version of `$` because it is a unary operator.
421
422The assignment versions of the above operators are not available in `dc`, but
423the others are, as the operators `$`, `@`, `H`, and `h`, respectively.
424
425In addition, this `bc` has the option of outputting in scientific notation or
426engineering notation. It can also take input in scientific or engineering
427notation. On top of that, it has a pseudo-random number generator. (See the
428full manual for more details.)
429
430Extra operators, scientific notation, engineering notation, and the
431pseudo-random number generator can be disabled by passing either the `-E` flag
432or the `--disable-extra-math` option to `configure.sh`, as follows:
433
434```
435./configure.sh -E
436./configure.sh --disable-extra-math
437```
438
439Both commands are equivalent.
440
441This `bc` also has a larger library that is only enabled if extra operators and
442the pseudo-random number generator are. More information about the functions can
443be found in the Extended Library section of the full manual.
444
445### Manpages
446
447To 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
455Both commands are equivalent.
456
457### Karatsuba Length
458
459The Karatsuba length is the point at which `bc` and `dc` switch from Karatsuba
460multiplication to brute force, `O(n^2)` multiplication. It can be set by passing
461the `-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
468Both commands are equivalent.
469
470Default is `64`.
471
472***WARNING***: The Karatsuba Length must be a **integer** greater than or equal
473to `16` (to prevent stack overflow). If it is not, `configure.sh` will give an
474error.
475
476### Install Options
477
478The 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
488An example is:
489
490```
491./configure.sh --prefix=/usr --localedir /usr/share/nls
492make
493make install
494```
495
496They correspond to the environment variables `$PREFIX`, `$BINDIR`,
497`$DATAROOTDIR`, `$DATADIR`, `$MANDIR`, `$MAN1DIR`, and `$LOCALEDIR`,
498respectively.
499
500***WARNING***: If the option is given, the value of the corresponding
501environment variable is overridden.
502
503***WARNING***: If any long command-line options are used, the long form of all
504other command-line options must be used. Mixing long and short options is not
505supported.
506
507## Optimization
508
509The `configure.sh` script will accept an optimization level to pass to the
510compiler. Because `bc` is orders of magnitude faster with optimization, I
511***highly*** recommend package and distro maintainers pass the highest
512optimization 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
520Both commands are equivalent.
521
522The build and install can then be run as normal:
523
524```
525make
526make install
527```
528
529As usual, `configure.sh` will also accept additional `CFLAGS` on the command
530line, so for SSE4 architectures, the following can add a bit more speed:
531
532```
533CFLAGS="-march=native -msse4" ./configure.sh -O3
534make
535make install
536```
537
538Building with link-time optimization (`-flto` in clang) can further increase the
539performance. I ***highly*** recommend doing so.
540
541I do **NOT*** recommend building with `-march=native`; doing so reduces this
542`bc`'s performance.
543
544Manual stripping is not necessary; non-debug builds are automatically stripped
545in the link stage.
546
547## Debug Builds
548
549Debug builds (which also disable optimization if no optimization level is given
550and if no extra `CFLAGS` are given) can be enabled with either the `-g` flag or
551the `--debug` option, as follows:
552
553```
554./configure.sh -g
555./configure.sh --debug
556```
557
558Both commands are equivalent.
559
560The build and install can then be run as normal:
561
562```
563make
564make install
565```
566
567## Stripping Binaries
568
569By default, when `bc` and `dc` are not built in debug mode, the binaries are
570stripped. 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
578Both commands are equivalent.
579
580The build and install can then be run as normal:
581
582```
583make
584make install
585```
586
587## Binary Size
588
589When 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
591isn't much for what is contained in the binary, but if necessary, it can be
592reduced.
593
594The single largest user of space is the `bc` calculator. If just `dc` is needed,
595the size can be reduced to 107.6 kb (107,584 bytes).
596
597The next largest user of space is history support. If that is not needed, size
598can be reduced (for a build with both calculators) to 119.9 kb (119,866 bytes).
599
600There are several reasons that history is a bigger user of space than `dc`
601itself:
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
611The next biggest user is extra math support. Without it, the size is reduced to
612124.0 kb (123,986 bytes) with history and 107.6 kb (107,560 bytes) without
613history.
614
615The 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
625The next biggest user is `dc`, so if just `bc` is needed, the size can be
626reduced to 128.1 kb (128,096 bytes) with history and extra math support, 107.6
627kb (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`
633optimizations. These builds were done on an `x86_64` machine running Gentoo
634Linux.
635
636## Testing
637
638The default test suite can be run with the following command:
639
640```
641make test
642```
643
644To test `bc` only, run the following command:
645
646```
647make test_bc
648```
649
650To test `dc` only, run the following command:
651
652```
653make test_dc
654```
655
656This `bc`, if built, assumes a working, GNU-compatible `bc`, installed on the
657system 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
665After running `configure.sh`, build and run tests as follows:
666
667```
668make
669make test
670```
671
672This `dc` also assumes a working, GNU-compatible `dc`, installed on the system
673and in the `PATH`, to generate some tests, unless one of the above options is
674given to `configure.sh`.
675
676To 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
684Both 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
695