3 ***WARNING: This project has moved to [https://git.yzena.com/][20] for [these
4 reasons][21], though GitHub will remain a mirror.***
6 This is an implementation of the [POSIX `bc` calculator][12] that implements
7 [GNU `bc`][1] extensions, as well as the period (`.`) extension for the BSD
10 For more information, see this `bc`'s full manual.
12 This `bc` also includes an implementation of `dc` in the same binary, accessible
13 via a symbolic link, which implements all FreeBSD and GNU extensions. (If a
14 standalone `dc` binary is desired, `bc` can be copied and renamed to `dc`.) The
15 `!` command is omitted; I believe this poses security concerns and that such
16 functionality is unnecessary.
18 For more information, see the `dc`'s full manual.
20 This `bc` also provides `bc`'s math as a library with C bindings, called `bcl`.
22 For more information, see the full manual for `bcl`.
26 This `bc` is Free and Open Source Software (FOSS). It is offered under the BSD
27 2-clause License. Full license text may be found in the [`LICENSE.md`][4] file.
31 This `bc` only requires either:
33 1. Windows 10 or later, or
34 2. A C99-compatible compiler and a (mostly) POSIX 2008-compatible system with
35 the XSI (X/Open System Interfaces) option group.
37 Since POSIX 2008 with XSI requires the existence of a C99 compiler as `c99`, any
38 POSIX and XSI-compatible system will have everything needed.
40 POSIX-compatible systems that are known to work:
47 * Solaris* (as long as the Solaris version supports POSIX 2008)
49 * HP-UX* (except for history)
51 In addition, there is compatibility code to make this `bc` work on Windows.
53 Please submit bug reports if this `bc` does not build out of the box on any
58 This `bc` should build unmodified on any POSIX-compliant system or on Windows
59 starting with Windows 10 (though earlier versions may work).
61 For more complex build requirements than the ones below, see the
66 There is no guarantee that this `bc` will work on any version of Windows earlier
67 than Windows 10 (I cannot test on earlier versions), but it is guaranteed to
68 work on Windows 10 at least.
70 Also, if building with MSBuild, the MSBuild bundled with Visual Studio is
73 **Note**: Unlike the POSIX-compatible platforms, only one build configuration is
74 supported on Windows: extra math and prompt enabled, history and NLS (locale
75 support) disabled, with both calculators built.
79 To build `bc`, you can open the `bc.sln` file in Visual Studio, select the
80 configuration, and build.
82 You can also build using MSBuild with the following from the root directory:
85 msbuild -property:Configuration=<config> bc.sln
88 where `<config>` is either one of `Debug` or `Release`.
92 To build the library, you can open the `bcl.sln` file in Visual Studio, select
93 the configuration, and build.
95 You can also build using MSBuild with the following from the root directory:
98 msbuild -property:Configuration=<config> bcl.sln
101 where `<config>` is either one of `Debug` or `Release`.
103 ### POSIX-Compatible Systems
105 On POSIX-compatible systems, `bc` is built as `bin/bc` and `dc` is built as
106 `bin/dc` by default. On Windows, they are built as `Release/bc/bc.exe` and
109 **Note**: On Windows, `dc.exe` is just copied from `bc.exe`; it is not linked.
110 Patches are welcome for a way to do that.
114 For the default build with optimization, use the following commands in the root
124 To only build `bc`, use the following commands:
127 ./configure.sh --disable-dc
131 To only build `dc`, use the following commands:
134 ./configure.sh --disable-bc
140 For debug builds, use the following commands in the root directory:
149 To install, use the following command:
155 By default, `bc` and `dc` will be installed in `/usr/local`. For installing in
156 other locations, use the `PREFIX` environment variable when running
157 `configure.sh` or pass the `--prefix=<prefix>` option to `configure.sh`. See the
158 [build manual][5], or run `./configure.sh --help`, for more details.
162 This `bc` does provide a way to build a math library with C bindings. This is
163 done by the `-a` or `--library` options to `configure.sh`:
169 When building the library, the executables are not built. For more information,
170 see the [build manual][5].
172 The library API can be found in [`manuals/bcl.3.md`][26] or `man bcl` once the
173 library is installed.
175 The library is built as `bin/libbcl.a` on POSIX-compatible systems or as
176 `Release/bcl/bcl.lib` on Windows.
178 #### Package and Distro Maintainers
180 ##### Recommended Compiler
182 When I ran benchmarks with my `bc` compiled under `clang`, it performed much
183 better than when compiled under `gcc`. I recommend compiling this `bc` with
186 I also recommend building this `bc` with C11 if you can because `bc` will detect
187 a C11 compiler and add `_Noreturn` to any relevant function(s).
189 ##### Recommended Optimizations
191 I wrote this `bc` with Separation of Concerns, which means that there are many
192 small functions that could be inlined. However, they are often called across
193 file boundaries, and the default optimizer can only look at the current file,
194 which means that they are not inlined.
196 Thus, because of the way this `bc` is built, it will automatically be slower
197 than other `bc` implementations when running scripts with no math. (My `bc`'s
198 math is *much* faster, so any non-trivial script should run faster in my `bc`.)
200 Some, or all, of the difference can be made up with the right optimizations. The
201 optimizations I recommend are:
204 2. `-flto` (link-time optimization)
208 Link-time optimization, in particular, speeds up the `bc` a lot. This is because
209 when link-time optimization is turned on, the optimizer can look across files
210 and inline *much* more heavily.
212 However, I recommend ***NOT*** using `-march=native`. Doing so will reduce this
213 `bc`'s performance, at least when building with link-time optimization. See the
214 [benchmarks][19] for more details.
216 ##### Stripping Binaries
218 By default, non-debug binaries are stripped, but stripping can be disabled with
219 the `-T` option to `configure.sh`.
221 ##### Using This `bc` as an Alternative
223 If this `bc` is packaged as an alternative to an already existing `bc` package,
224 it is possible to rename it in the build to prevent name collision. To prepend
225 to the name, just run the following:
228 EXECPREFIX=<some_prefix> ./configure.sh
231 To append to the name, just run the following:
234 EXECSUFFIX=<some_suffix> ./configure.sh
237 If a package maintainer wishes to add both a prefix and a suffix, that is
240 **Note**: The suggested name (and package name) when `bc` is not available is
243 ##### Karatsuba Number
245 Package and distro maintainers have one tool at their disposal to build this
246 `bc` in the optimal configuration: `scripts/karatsuba.py`.
248 This script is not a compile-time or runtime prerequisite; it is for package and
249 distro maintainers to run once when a package is being created. It finds the
250 optimal Karatsuba number (see the [algorithms manual][7] for more information)
251 for the machine that it is running on.
253 The easiest way to run this script is with `make karatsuba`.
255 If desired, maintainers can also skip running this script because there is a
256 sane default for the Karatsuba number.
262 It is well-tested, fuzzed, and fully standards-compliant (though not certified)
263 with POSIX `bc`. The math has been tested with 40+ million random problems, so
264 it is as correct as I can make it.
266 This `bc` can be used as a drop-in replacement for any existing `bc`. This `bc`
267 is also compatible with MinGW toolchains, though history is not supported on
270 In addition, this `bc` is considered complete; i.e., there will be no more
271 releases with additional features. However, it *is* actively maintained, so if
272 any bugs are found, they will be fixed in new releases. Also, additional
273 translations will also be added as they are provided.
277 If I (Gavin D. Howard) get [hit by a bus][27] and future programmers need to
278 handle work themselves, the best place to start is the [Development manual][28].
282 I have developed (using other people's code to start) [`vim` syntax files][17]
283 for this `bc` and `dc`, including the extensions.
287 I have gathered some excellent [`bc` and `dc` libraries][18]. These libraries
288 may prove useful to any serious users.
290 ## Comparison to GNU `bc`
292 This `bc` compares favorably to GNU `bc`.
294 * This `bc` builds natively on Windows.
295 * It has more extensions, which make this `bc` more useful for scripting.
296 * This `bc` is a bit more POSIX compliant.
297 * It has a much less buggy parser. The GNU `bc` will give parse errors for what
298 is actually valid `bc` code, or should be. For example, putting an `else` on
299 a new line after a brace can cause GNU `bc` to give a parse error.
300 * This `bc` has fewer crashes.
301 * GNU `bc` calculates the wrong number of significant digits for `length(x)`.
302 * GNU `bc` will sometimes print numbers incorrectly. For example, when running
303 it on the file `tests/bc/power.txt` in this repo, GNU `bc` gets all the right
304 answers, but it fails to wrap the numbers at the proper place when outputting
306 * This `bc` is faster. (See [Performance](#performance).)
310 Because this `bc` packs more than `1` decimal digit per hardware integer, this
311 `bc` is faster than GNU `bc` and can be *much* faster. Full benchmarks can be
312 found at [manuals/benchmarks.md][19].
314 There is one instance where this `bc` is slower: if scripts are light on math.
315 This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but
316 that is because it is more robust. See the [benchmarks][19].
320 To see what algorithms this `bc` uses, see the [algorithms manual][7].
324 Currently, there is no locale support on Windows.
326 Additionally, this `bc` only has support for English (and US English), French,
327 German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales.
328 Patches are welcome for translations; use the existing `*.msg` files in
329 `locales/` as a starting point.
331 In addition, patches for improvements are welcome; the last two messages in
332 Portuguese were made with Google Translate, and the Dutch, Polish, Russian,
333 Japanese, and Chinese locales were all generated with [DeepL][22].
335 The message files provided assume that locales apply to all regions where a
336 language is used, but this might not be true for, e.g., `fr_CA` and `fr_CH`.
337 Any corrections or a confirmation that the current texts are acceptable for
338 those regions would be appreciated, too.
342 Other projects based on this bc are:
344 * [busybox `bc`][8]. The busybox maintainers have made their own changes, so any
345 bugs in the busybox `bc` should be reported to them.
347 * [toybox `bc`][9]. The maintainer has also made his own changes, so bugs in the
348 toybox `bc` should be reported there.
350 * [FreeBSD `bc`][23]. While the `bc` in FreeBSD is kept up-to-date, it is better
351 to [report bugs there][24], as well as [submit patches][25], and the
352 maintainers of the package will contact me if necessary.
356 This `bc` is written in pure ISO C99, using POSIX 2008 APIs with custom Windows
361 This `bc` uses the commit message guidelines laid out in [this blog post][10].
363 ## Semantic Versioning
365 This `bc` uses [semantic versioning][11].
369 Items labeled with `(maintainer use only)` are not included in release source
374 .gitignore The git ignore file (maintainer use only).
375 .gitattributes The git attributes file (maintainer use only).
376 bc.sln The Visual Studio solution file for bc.
377 bc.vcxproj The Visual Studio project file for bc.
378 bc.vcxproj.filters The Visual Studio filters file for bc.
379 bcl.sln The Visual Studio solution file for bcl.
380 bcl.vcxproj The Visual Studio project file for bcl.
381 bcl.vcxproj.filters The Visual Studio filters file for bcl.
382 configure A symlink to configure.sh to make packaging easier.
383 configure.sh The configure script.
384 LICENSE.md A Markdown form of the BSD 2-clause License.
385 Makefile.in The Makefile template.
386 NOTICE.md List of contributors and copyright owners.
387 RELEASE.md A checklist for making a release (maintainer use only).
391 gen The bc math library, help texts, and code to generate C source.
392 include All header files.
393 locales Locale files, in .msg format. Patches welcome for translations.
394 manuals Manuals for both programs.
396 scripts A bunch of shell scripts to help with development and building.
399 [1]: https://www.gnu.org/software/bc/
401 [5]: ./manuals/build.md
402 [7]: ./manuals/algorithms.md
403 [8]: https://git.busybox.net/busybox/tree/miscutils/bc.c
404 [9]: https://github.com/landley/toybox/blob/master/toys/pending/bc.c
405 [10]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
406 [11]: http://semver.org/
407 [12]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
408 [17]: https://git.yzena.com/gavin/vim-bc
409 [18]: https://git.yzena.com/gavin/bc_libs
410 [19]: ./manuals/benchmarks.md
411 [20]: https://git.yzena.com/gavin/bc
412 [21]: https://gavinhoward.com/2020/04/i-am-moving-away-from-github/
413 [22]: https://www.deepl.com/translator
414 [23]: https://cgit.freebsd.org/src/tree/contrib/bc
415 [24]: https://bugs.freebsd.org/
416 [25]: https://reviews.freebsd.org/
417 [26]: ./manuals/bcl.3.md
418 [27]: https://en.wikipedia.org/wiki/Bus_factor
419 [28]: ./manuals/development.md