3 [![Build Status][13]][14]
5 [![Coverity Scan Build Status][17]][18]
7 ***WARNING: This project has moved to [https://git.yzena.com/][20] for [these
8 reasons][21], though GitHub will remain a mirror.***
10 This is an implementation of the [POSIX `bc` calculator][12] that implements
11 [GNU `bc`][1] extensions, as well as the period (`.`) extension for the BSD
14 For more information, see this `bc`'s full manual.
16 This `bc` also includes an implementation of `dc` in the same binary, accessible
17 via a symbolic link, which implements all FreeBSD and GNU extensions. (If a
18 standalone `dc` binary is desired, `bc` can be copied and renamed to `dc`.) The
19 `!` command is omitted; I believe this poses security concerns and that such
20 functionality is unnecessary.
22 For more information, see the `dc`'s full manual.
24 This `bc` is Free and Open Source Software (FOSS). It is offered under the BSD
25 2-clause License. Full license text may be found in the [`LICENSE.md`][4] file.
29 This `bc` only requires a C99-compatible compiler and a (mostly) POSIX
30 2008-compatible system with the XSI (X/Open System Interfaces) option group.
32 Since POSIX 2008 with XSI requires the existence of a C99 compiler as `c99`, any
33 POSIX and XSI-compatible system will have everything needed.
35 Systems that are known to work:
42 * Solaris* (as long as the Solaris version supports POSIX 2008)
45 Please submit bug reports if this `bc` does not build out of the box on any
46 system besides Windows. If Windows binaries are needed, they can be found at
51 This `bc` should build unmodified on any POSIX-compliant system.
53 For more complex build requirements than the ones below, see the
56 ### Pre-built Binaries
58 It is possible to download pre-compiled binaries for a wide list of platforms,
59 including Linux- and Windows-based systems, from [xstatic][6]. This link always
60 points to the latest release of `bc`.
64 For the default build with optimization, use the following commands in the root
74 To only build `bc`, use the following commands:
77 ./configure.sh --disable-dc
81 To only build `dc`, use the following commands:
84 ./configure.sh --disable-bc
90 For debug builds, use the following commands in the root directory:
99 To install, use the following command:
105 By default, `bc` and `dc` will be installed in `/usr/local`. For installing in
106 other locations, use the `PREFIX` environment variable when running
107 `configure.sh` or pass the `--prefix=<prefix>` option to `configure.sh`. See the
108 [build manual][5], or run `./configure.sh --help`, for more details.
112 This `bc` does provide a way to build a math library with C bindings. This is
113 done by the `-a` or `--library` options to `configure.sh`:
119 When building the library, the executables are not built. For more information,
120 see the [build manual][5].
122 The library API can be found in [`manuals/bcl.3.md`][26] or `man bcl` once the
123 library is installed.
125 The library is built as `bin/libbcl.a`.
127 ### Package and Distro Maintainers
129 #### Recommended Compiler
131 When I ran benchmarks with my `bc` compiled under `clang`, it performed much
132 better than when compiled under `gcc`. I recommend compiling this `bc` with
135 I also recommend building this `bc` with C11 if you can because `bc` will detect
136 a C11 compiler and add `_Noreturn` to any relevant function(s).
138 #### Recommended Optimizations
140 I wrote this `bc` with Separation of Concerns, which means that there are many
141 small functions that could be inlined. However, they are often called across
142 file boundaries, and the default optimizer can only look at the current file,
143 which means that they are not inlined.
145 Thus, because of the way this `bc` is built, it will automatically be slower
146 than other `bc` implementations when running scripts with no math. (My `bc`'s
147 math is *much* faster, so any non-trivial script should run faster in my `bc`.)
149 Some, or all, of the difference can be made up with the right optimizations. The
150 optimizations I recommend are:
153 2. `-flto` (link-time optimization)
157 Link-time optimization, in particular, speeds up the `bc` a lot. This is because
158 when link-time optimization is turned on, the optimizer can look across files
159 and inline *much* more heavily.
161 However, I recommend ***NOT*** using `-march=native`. Doing so will reduce this
162 `bc`'s performance, at least when building with link-time optimization. See the
163 [benchmarks][19] for more details.
165 #### Stripping Binaries
167 By default, non-debug binaries are stripped, but stripping can be disabled with
168 the `-T` option to `configure.sh`.
170 #### Using This `bc` as an Alternative
172 If this `bc` is packaged as an alternative to an already existing `bc` package,
173 it is possible to rename it in the build to prevent name collision. To prepend
174 to the name, just run the following:
177 EXECPREFIX=<some_prefix> ./configure.sh
180 To append to the name, just run the following:
183 EXECSUFFIX=<some_suffix> ./configure.sh
186 If a package maintainer wishes to add both a prefix and a suffix, that is
189 **Note**: The suggested name (and package name) when `bc` is not available is
192 #### Karatsuba Number
194 Package and distro maintainers have one tool at their disposal to build this
195 `bc` in the optimal configuration: `karatsuba.py`.
197 This script is not a compile-time or runtime prerequisite; it is for package and
198 distro maintainers to run once when a package is being created. It finds the
199 optimal Karatsuba number (see the [algorithms manual][7] for more information)
200 for the machine that it is running on.
202 The easiest way to run this script is with `make karatsuba`.
204 If desired, maintainers can also skip running this script because there is a
205 sane default for the Karatsuba number.
211 It is well-tested, fuzzed, and fully standards-compliant (though not certified)
212 with POSIX `bc`. The math has been tested with 40+ million random problems, so
213 it is as correct as I can make it.
215 This `bc` can be used as a drop-in replacement for any existing `bc`. This `bc`
216 is also compatible with MinGW toolchains, though history is not supported on
219 In addition, this `bc` is considered complete; i.e., there will be no more
220 releases with additional features. However, it *is* actively maintained, so if
221 any bugs are found, they will be fixed in new releases. Also, additional
222 translations will also be added as they are provided.
224 ## Comparison to GNU `bc`
226 This `bc` compares favorably to GNU `bc`.
228 * It has more extensions, which make this `bc` more useful for scripting.
229 * This `bc` is a bit more POSIX compliant.
230 * It has a much less buggy parser. The GNU `bc` will give parse errors for what
231 is actually valid `bc` code, or should be. For example, putting an `else` on
232 a new line after a brace can cause GNU `bc` to give a parse error.
233 * This `bc` has fewer crashes.
234 * GNU `bc` calculates the wrong number of significant digits for `length(x)`.
235 * GNU `bc` will sometimes print numbers incorrectly. For example, when running
236 it on the file `tests/bc/power.txt` in this repo, GNU `bc` gets all the right
237 answers, but it fails to wrap the numbers at the proper place when outputting
239 * This `bc` is faster. (See [Performance](#performance).)
243 Because this `bc` packs more than `1` decimal digit per hardware integer, this
244 `bc` is faster than GNU `bc` and can be *much* faster. Full benchmarks can be
245 found at [manuals/benchmarks.md][19].
247 There is one instance where this `bc` is slower: if scripts are light on math.
248 This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but
249 that is because it is more robust. See the [benchmarks][19].
253 To see what algorithms this `bc` uses, see the [algorithms manual][7].
257 Currently, this `bc` only has support for English (and US English), French,
258 German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales.
259 Patches are welcome for translations; use the existing `*.msg` files in
260 `locales/` as a starting point.
262 In addition, patches for improvements are welcome; the last two messages in
263 Portuguese were made with Google Translate, and the Dutch, Polish, Russian,
264 Japanese, and Chinese locales were all generated with [DeepL][22].
266 The message files provided assume that locales apply to all regions where a
267 language is used, but this might not be true for, e.g., `fr_CA` and `fr_CH`.
268 Any corrections or a confirmation that the current texts are acceptable for
269 those regions would be appreciated, too.
273 Other projects based on this bc are:
275 * [busybox `bc`][8]. The busybox maintainers have made their own changes, so any
276 bugs in the busybox `bc` should be reported to them.
278 * [toybox `bc`][9]. The maintainer has also made his own changes, so bugs in the
279 toybox `bc` should be reported there.
281 * [FreeBSD `bc`][23]. While the `bc` in FreeBSD is kept up-to-date, it is better
282 to [report bugs there][24], as well as [submit patches][25], and the
283 maintainers of the package will contact me if necessary.
287 This `bc` is written in pure ISO C99, using POSIX 2008 APIs.
291 This `bc` uses the commit message guidelines laid out in [this blog post][10].
293 ## Semantic Versioning
295 This `bc` uses [semantic versioning][11].
299 Items labeled with `(maintainer use only)` are not included in release source
304 .gitignore The git ignore file (maintainer use only).
305 .travis.yml The Travis CI file (maintainer use only).
306 codecov.yml The Codecov file (maintainer use only).
307 configure A symlink to configure.sh to make packaging easier.
308 configure.sh The configure script.
309 functions.sh A script with functions used by other scripts.
310 install.sh Install script.
311 karatsuba.py Script to find the optimal Karatsuba number.
312 LICENSE.md A Markdown form of the BSD 2-clause License.
313 link.sh A script to link dc to bc.
314 locale_install.sh A script to install locales, if desired.
315 locale_uninstall.sh A script to uninstall locales.
316 Makefile.in The Makefile template.
317 manpage.sh Script to generate man pages from markdown files.
318 NOTICE.md List of contributors and copyright owners.
319 RELEASE.md A checklist for making a release (maintainer use only).
320 release.sh A script to test for release (maintainer use only).
321 safe-install.sh Safe install script from musl libc.
325 gen The bc math library, help texts, and code to generate C source.
326 include All header files.
327 locales Locale files, in .msg format. Patches welcome for translations.
328 manuals Manuals for both programs.
332 [1]: https://www.gnu.org/software/bc/
334 [5]: ./manuals/build.md
335 [6]: https://pkg.musl.cc/bc/
336 [7]: ./manuals/algorithms.md
337 [8]: https://git.busybox.net/busybox/tree/miscutils/bc.c
338 [9]: https://github.com/landley/toybox/blob/master/toys/pending/bc.c
339 [10]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
340 [11]: http://semver.org/
341 [12]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
342 [13]: https://travis-ci.com/gavinhoward/bc.svg?branch=master
343 [14]: https://travis-ci.com/gavinhoward/bc
344 [15]: https://codecov.io/gh/gavinhoward/bc/branch/master/graph/badge.svg
345 [16]: https://codecov.io/gh/gavinhoward/bc
346 [17]: https://img.shields.io/coverity/scan/16609.svg
347 [18]: https://scan.coverity.com/projects/gavinhoward-bc
348 [19]: ./manuals/benchmarks.md
349 [20]: https://git.yzena.com/gavin/bc
350 [21]: https://gavinhoward.com/2020/04/i-am-moving-away-from-github/
351 [22]: https://www.deepl.com/translator
352 [23]: https://svnweb.freebsd.org/base/head/contrib/bc/
353 [24]: https://bugs.freebsd.org/
354 [25]: https://reviews.freebsd.org/
355 [26]: ./manuals/bcl.3.md