3 [![Coverity Scan Build Status][17]][18]
5 ***WARNING: This project has moved to [https://git.yzena.com/][20] for [these
6 reasons][21], though GitHub will remain a mirror.***
8 This is an implementation of the [POSIX `bc` calculator][12] that implements
9 [GNU `bc`][1] extensions, as well as the period (`.`) extension for the BSD
12 For more information, see this `bc`'s full manual.
14 This `bc` also includes an implementation of `dc` in the same binary, accessible
15 via a symbolic link, which implements all FreeBSD and GNU extensions. (If a
16 standalone `dc` binary is desired, `bc` can be copied and renamed to `dc`.) The
17 `!` command is omitted; I believe this poses security concerns and that such
18 functionality is unnecessary.
20 For more information, see the `dc`'s full manual.
22 This `bc` is Free and Open Source Software (FOSS). It is offered under the BSD
23 2-clause License. Full license text may be found in the [`LICENSE.md`][4] file.
27 This `bc` only requires either:
29 1. Windows 10 or later, or
30 2. A C99-compatible compiler and a (mostly) POSIX 2008-compatible system with
31 the XSI (X/Open System Interfaces) option group.
33 Since POSIX 2008 with XSI requires the existence of a C99 compiler as `c99`, any
34 POSIX and XSI-compatible system will have everything needed.
36 POSIX-compatible systems that are known to work:
43 * Solaris* (as long as the Solaris version supports POSIX 2008)
45 * HP-UX* (except for history)
47 In addition, there is compatibility code to make this `bc` work on Windows.
49 Please submit bug reports if this `bc` does not build out of the box on any
56 There is no guarantee that this `bc` will work on any version of Windows earlier
57 than Windows 10 (I cannot test on earlier versions), but it is guaranteed to
58 work on Windows 10 at least.
60 Also, if building with MSBuild, the MSBuild bundled with Visual Studio is
63 **Note**: Unlike the POSIX-compatible platforms, only one build configuration is
64 supported on Windows: extra math and prompt enabled, history and NLS (locale
65 support) disabled, with both calculators built.
69 To build `bc`, you can open the `bc.sln` file in Visual Studio, select the
70 configuration, and build.
72 You can also build using MSBuild with the following from the root directory:
75 msbuild -property:Configuration=<config> bc.sln
78 where `<config>` is either one of `Debug` or `Release`.
82 To build the library, you can open the `bcl.sln` file in Visual Studio, select
83 the configuration, and build.
85 You can also build using MSBuild with the following from the root directory:
88 msbuild -property:Configuration=<config> bcl.sln
91 where `<config>` is either one of `Debug` or `Release`.
93 ### POSIX-Compatible Systems
95 This `bc` should build unmodified on any POSIX-compliant system or on Windows
96 starting with Windows 10 (though earlier versions may work).
98 For more complex build requirements than the ones below, see the
101 On POSIX-compatible systems, `bc` is built as `bin/bc` and `dc` is built as
102 `bin/dc` by default. On Windows, they are built as `Release/bc/bc.exe` and
105 **Note**: On Windows, `dc.exe` is just copied from `bc.exe`; it is not linked.
106 Patches are welcome for a way to do that.
110 For the default build with optimization, use the following commands in the root
120 To only build `bc`, use the following commands:
123 ./configure.sh --disable-dc
127 To only build `dc`, use the following commands:
130 ./configure.sh --disable-bc
136 For debug builds, use the following commands in the root directory:
145 To install, use the following command:
151 By default, `bc` and `dc` will be installed in `/usr/local`. For installing in
152 other locations, use the `PREFIX` environment variable when running
153 `configure.sh` or pass the `--prefix=<prefix>` option to `configure.sh`. See the
154 [build manual][5], or run `./configure.sh --help`, for more details.
158 This `bc` does provide a way to build a math library with C bindings. This is
159 done by the `-a` or `--library` options to `configure.sh`:
165 When building the library, the executables are not built. For more information,
166 see the [build manual][5].
168 The library API can be found in [`manuals/bcl.3.md`][26] or `man bcl` once the
169 library is installed.
171 The library is built as `bin/libbcl.a` on POSIX-compatible systems or as
172 `Release/bcl/bcl.lib` on Windows.
174 #### Package and Distro Maintainers
176 ##### Recommended Compiler
178 When I ran benchmarks with my `bc` compiled under `clang`, it performed much
179 better than when compiled under `gcc`. I recommend compiling this `bc` with
182 I also recommend building this `bc` with C11 if you can because `bc` will detect
183 a C11 compiler and add `_Noreturn` to any relevant function(s).
185 ##### Recommended Optimizations
187 I wrote this `bc` with Separation of Concerns, which means that there are many
188 small functions that could be inlined. However, they are often called across
189 file boundaries, and the default optimizer can only look at the current file,
190 which means that they are not inlined.
192 Thus, because of the way this `bc` is built, it will automatically be slower
193 than other `bc` implementations when running scripts with no math. (My `bc`'s
194 math is *much* faster, so any non-trivial script should run faster in my `bc`.)
196 Some, or all, of the difference can be made up with the right optimizations. The
197 optimizations I recommend are:
200 2. `-flto` (link-time optimization)
204 Link-time optimization, in particular, speeds up the `bc` a lot. This is because
205 when link-time optimization is turned on, the optimizer can look across files
206 and inline *much* more heavily.
208 However, I recommend ***NOT*** using `-march=native`. Doing so will reduce this
209 `bc`'s performance, at least when building with link-time optimization. See the
210 [benchmarks][19] for more details.
212 ##### Stripping Binaries
214 By default, non-debug binaries are stripped, but stripping can be disabled with
215 the `-T` option to `configure.sh`.
217 ##### Using This `bc` as an Alternative
219 If this `bc` is packaged as an alternative to an already existing `bc` package,
220 it is possible to rename it in the build to prevent name collision. To prepend
221 to the name, just run the following:
224 EXECPREFIX=<some_prefix> ./configure.sh
227 To append to the name, just run the following:
230 EXECSUFFIX=<some_suffix> ./configure.sh
233 If a package maintainer wishes to add both a prefix and a suffix, that is
236 **Note**: The suggested name (and package name) when `bc` is not available is
239 ##### Karatsuba Number
241 Package and distro maintainers have one tool at their disposal to build this
242 `bc` in the optimal configuration: `karatsuba.py`.
244 This script is not a compile-time or runtime prerequisite; it is for package and
245 distro maintainers to run once when a package is being created. It finds the
246 optimal Karatsuba number (see the [algorithms manual][7] for more information)
247 for the machine that it is running on.
249 The easiest way to run this script is with `make karatsuba`.
251 If desired, maintainers can also skip running this script because there is a
252 sane default for the Karatsuba number.
258 It is well-tested, fuzzed, and fully standards-compliant (though not certified)
259 with POSIX `bc`. The math has been tested with 40+ million random problems, so
260 it is as correct as I can make it.
262 This `bc` can be used as a drop-in replacement for any existing `bc`. This `bc`
263 is also compatible with MinGW toolchains, though history is not supported on
266 In addition, this `bc` is considered complete; i.e., there will be no more
267 releases with additional features. However, it *is* actively maintained, so if
268 any bugs are found, they will be fixed in new releases. Also, additional
269 translations will also be added as they are provided.
271 ## Comparison to GNU `bc`
273 This `bc` compares favorably to GNU `bc`.
275 * This `bc` builds natively on Windows.
276 * It has more extensions, which make this `bc` more useful for scripting.
277 * This `bc` is a bit more POSIX compliant.
278 * It has a much less buggy parser. The GNU `bc` will give parse errors for what
279 is actually valid `bc` code, or should be. For example, putting an `else` on
280 a new line after a brace can cause GNU `bc` to give a parse error.
281 * This `bc` has fewer crashes.
282 * GNU `bc` calculates the wrong number of significant digits for `length(x)`.
283 * GNU `bc` will sometimes print numbers incorrectly. For example, when running
284 it on the file `tests/bc/power.txt` in this repo, GNU `bc` gets all the right
285 answers, but it fails to wrap the numbers at the proper place when outputting
287 * This `bc` is faster. (See [Performance](#performance).)
291 Because this `bc` packs more than `1` decimal digit per hardware integer, this
292 `bc` is faster than GNU `bc` and can be *much* faster. Full benchmarks can be
293 found at [manuals/benchmarks.md][19].
295 There is one instance where this `bc` is slower: if scripts are light on math.
296 This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but
297 that is because it is more robust. See the [benchmarks][19].
301 To see what algorithms this `bc` uses, see the [algorithms manual][7].
305 Currently, there is no locale support on Windows.
307 Additionally, this `bc` only has support for English (and US English), French,
308 German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales.
309 Patches are welcome for translations; use the existing `*.msg` files in
310 `locales/` as a starting point.
312 In addition, patches for improvements are welcome; the last two messages in
313 Portuguese were made with Google Translate, and the Dutch, Polish, Russian,
314 Japanese, and Chinese locales were all generated with [DeepL][22].
316 The message files provided assume that locales apply to all regions where a
317 language is used, but this might not be true for, e.g., `fr_CA` and `fr_CH`.
318 Any corrections or a confirmation that the current texts are acceptable for
319 those regions would be appreciated, too.
323 Other projects based on this bc are:
325 * [busybox `bc`][8]. The busybox maintainers have made their own changes, so any
326 bugs in the busybox `bc` should be reported to them.
328 * [toybox `bc`][9]. The maintainer has also made his own changes, so bugs in the
329 toybox `bc` should be reported there.
331 * [FreeBSD `bc`][23]. While the `bc` in FreeBSD is kept up-to-date, it is better
332 to [report bugs there][24], as well as [submit patches][25], and the
333 maintainers of the package will contact me if necessary.
337 This `bc` is written in pure ISO C99, using POSIX 2008 APIs with custom Windows
342 This `bc` uses the commit message guidelines laid out in [this blog post][10].
344 ## Semantic Versioning
346 This `bc` uses [semantic versioning][11].
350 Items labeled with `(maintainer use only)` are not included in release source
355 .gitignore The git ignore file (maintainer use only).
356 .gitattributes The git attributes file (maintainer use only).
357 bc.sln The Visual Studio solution file for bc.
358 bc.vcxproj The Visual Studio project file for bc.
359 bc.vcxproj.filters The Visual Studio filters file for bc.
360 bcl.sln The Visual Studio solution file for bcl.
361 bcl.vcxproj The Visual Studio project file for bcl.
362 bcl.vcxproj.filters The Visual Studio filters file for bcl.
363 configure A symlink to configure.sh to make packaging easier.
364 configure.sh The configure script.
365 functions.sh A script with functions used by other scripts.
366 install.sh Install script.
367 karatsuba.py Script to find the optimal Karatsuba number.
368 LICENSE.md A Markdown form of the BSD 2-clause License.
369 link.sh A script to link dc to bc.
370 locale_install.sh A script to install locales, if desired.
371 locale_uninstall.sh A script to uninstall locales.
372 Makefile.in The Makefile template.
373 manpage.sh Script to generate man pages from markdown files
374 (maintainer use only).
375 NOTICE.md List of contributors and copyright owners.
376 RELEASE.md A checklist for making a release (maintainer use only).
377 release.sh A script to test for release (maintainer use only).
378 safe-install.sh Safe install script from musl libc.
382 gen The bc math library, help texts, and code to generate C source.
383 include All header files.
384 locales Locale files, in .msg format. Patches welcome for translations.
385 manuals Manuals for both programs.
389 [1]: https://www.gnu.org/software/bc/
391 [5]: ./manuals/build.md
392 [7]: ./manuals/algorithms.md
393 [8]: https://git.busybox.net/busybox/tree/miscutils/bc.c
394 [9]: https://github.com/landley/toybox/blob/master/toys/pending/bc.c
395 [10]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
396 [11]: http://semver.org/
397 [12]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
398 [17]: https://img.shields.io/coverity/scan/16609.svg
399 [18]: https://scan.coverity.com/projects/gavinhoward-bc
400 [19]: ./manuals/benchmarks.md
401 [20]: https://git.yzena.com/gavin/bc
402 [21]: https://gavinhoward.com/2020/04/i-am-moving-away-from-github/
403 [22]: https://www.deepl.com/translator
404 [23]: https://cgit.freebsd.org/src/tree/contrib/bc
405 [24]: https://bugs.freebsd.org/
406 [25]: https://reviews.freebsd.org/
407 [26]: ./manuals/bcl.3.md