3 ***WARNING: New user registration for <https://git.gavinhoward.com/> is disabled
4 because of spam. If you need to report a bug with `bc`, email gavin at this site
5 minus the `git.` part for an account, and I will create one for you. Or you can
6 report an issue at [GitHub][29].***
8 ***WARNING: This project has moved to [https://git.gavinhoward.com/][20] for
9 [these reasons][21], though GitHub will remain a mirror.***
11 This is an implementation of the [POSIX `bc` calculator][12] that implements
12 [GNU `bc`][1] extensions, as well as the period (`.`) extension for the BSD
15 For more information, see this `bc`'s full manual.
17 This `bc` also includes an implementation of `dc` in the same binary, accessible
18 via a symbolic link, which implements all FreeBSD and GNU extensions. (If a
19 standalone `dc` binary is desired, `bc` can be copied and renamed to `dc`.) The
20 `!` command is omitted; I believe this poses security concerns and that such
21 functionality is unnecessary.
23 For more information, see the `dc`'s full manual.
25 This `bc` also provides `bc`'s math as a library with C bindings, called `bcl`.
27 For more information, see the full manual for `bcl`.
31 This `bc` is Free and Open Source Software (FOSS). It is offered under the BSD
32 2-clause License. Full license text may be found in the [`LICENSE.md`][4] file.
36 This `bc` only requires either:
38 1. Windows 10 or later, or
39 2. A C99-compatible compiler and a (mostly) POSIX 2008-compatible system with
40 the XSI (X/Open System Interfaces) option group.
42 Since POSIX 2008 with XSI requires the existence of a C99 compiler as `c99`, any
43 POSIX and XSI-compatible system will have everything needed.
45 POSIX-compatible systems that are known to work:
52 * Solaris* (as long as the Solaris version supports POSIX 2008)
54 * HP-UX* (except for history)
56 In addition, there is compatibility code to make this `bc` work on Windows.
58 Please submit bug reports if this `bc` does not build out of the box on any
63 This `bc` should build unmodified on any POSIX-compliant system or on Windows
64 starting with Windows 10 (though earlier versions may work).
66 For more complex build requirements than the ones below, see the [build
71 There is no guarantee that this `bc` will work on any version of Windows earlier
72 than Windows 10 (I cannot test on earlier versions), but it is guaranteed to
73 work on Windows 10 at least.
75 Also, if building with MSBuild, the MSBuild bundled with Visual Studio is
78 **Note**: Unlike the POSIX-compatible platforms, only one build configuration is
79 supported on Windows: extra math and history enabled, NLS (locale support)
80 disabled, with both calculators built.
84 To build `bc`, you can open the `vs/bc.sln` file in Visual Studio, select the
85 configuration, and build.
87 You can also build using MSBuild with the following from the root directory:
90 msbuild -property:Configuration=<config> vs/bc.sln
93 where `<config>` is either one of `Debug` or `Release`.
95 On Windows, the calculators are built as `vs/bin/<platform>/<config>/bc.exe` and
96 `vs/bin/<Platform>/<Config>/dc.exe`, where `<platform>` can be either `Win32` or
97 `x64`, and `<config>` can be `Debug` or `Release`.
99 **Note**: On Windows, `dc.exe` is just copied from `bc.exe`; it is not linked.
100 Patches are welcome for a way to do that.
104 To build the library, you can open the `vs/bcl.sln` file in Visual Studio,
105 select the configuration, and build.
107 You can also build using MSBuild with the following from the root directory:
110 msbuild -property:Configuration=<config> vs/bcl.sln
113 where `<config>` is either one of `Debug`, `ReleaseMD`, or `ReleaseMT`.
115 On Windows, the library is built as `vs/lib/<platform>/<config>/bcl.lib`, where
116 `<platform>` can be either `Win32` or `x64`, and `<config>` can be `Debug`,
117 `ReleaseMD`, or `ReleaseMT`.
119 ### POSIX-Compatible Systems
121 On POSIX-compatible systems, `bc` is built as `bin/bc` and `dc` is built as
126 For the default build with optimization, use the following commands in the root
136 To only build `bc`, use the following commands:
139 ./configure.sh --disable-dc
143 To only build `dc`, use the following commands:
146 ./configure.sh --disable-bc
152 For debug builds, use the following commands in the root directory:
161 To install, use the following command:
167 By default, `bc` and `dc` will be installed in `/usr/local`. For installing in
168 other locations, use the `PREFIX` environment variable when running
169 `configure.sh` or pass the `--prefix=<prefix>` option to `configure.sh`. See the
170 [build manual][5], or run `./configure.sh --help`, for more details.
174 To build the math library, pass the `-a` or `--library` options to
181 When building the library, the executables are not built. For more information,
182 see the [build manual][5].
184 The library API can be found in [`manuals/bcl.3.md`][26] or `man bcl` once the
185 library is installed.
187 #### Package and Distro Maintainers
189 This section is for package and distro maintainers.
191 ##### Out-of-Source Builds
193 Out-of-source builds are supported; just call `configure.sh` from the directory
194 where the actual build will happen.
196 For example, if the source is in `bc`, the build should happen in `build`, then
197 call `configure.sh` and `make` like so:
204 ***WARNING***: The path to `configure.sh` from the build directory must not have
205 spaces because `make` does not support target names with spaces.
207 ##### Recommended Compiler
209 When I ran benchmarks with my `bc` compiled under `clang`, it performed much
210 better than when compiled under `gcc`. I recommend compiling this `bc` with
213 I also recommend building this `bc` with C11 if you can because `bc` will detect
214 a C11 compiler and add `_Noreturn` to any relevant function(s).
216 ##### Recommended Optimizations
218 I wrote this `bc` with Separation of Concerns, which means that there are many
219 small functions that could be inlined. However, they are often called across
220 file boundaries, and the default optimizer can only look at the current file,
221 which means that they are not inlined.
223 Thus, because of the way this `bc` is built, it will automatically be slower
224 than other `bc` implementations when running scripts with no math. (My `bc`'s
225 math is *much* faster, so any non-trivial script should run faster in my `bc`.)
227 Some, or all, of the difference can be made up with the right optimizations. The
228 optimizations I recommend are:
231 2. `-flto` (link-time optimization)
235 Link-time optimization, in particular, speeds up the `bc` a lot. This is because
236 when link-time optimization is turned on, the optimizer can look across files
237 and inline *much* more heavily.
239 However, I recommend ***NOT*** using `-march=native`. Doing so will reduce this
240 `bc`'s performance, at least when building with link-time optimization. See the
241 [benchmarks][19] for more details.
243 ##### Stripping Binaries
245 By default, non-debug binaries are stripped, but stripping can be disabled with
246 the `-T` option to `configure.sh`.
248 ##### Using This `bc` as an Alternative
250 If this `bc` is packaged as an alternative to an already existing `bc` package,
251 it is possible to rename it in the build to prevent name collision. To prepend
252 to the name, just run the following:
255 EXECPREFIX=<some_prefix> ./configure.sh
258 To append to the name, just run the following:
261 EXECSUFFIX=<some_suffix> ./configure.sh
264 If a package maintainer wishes to add both a prefix and a suffix, that is
267 **Note**: The suggested name (and package name) when `bc` is not available is
270 ##### Karatsuba Number
272 Package and distro maintainers have one tool at their disposal to build this
273 `bc` in the optimal configuration: `scripts/karatsuba.py`.
275 This script is not a compile-time or runtime prerequisite; it is for package and
276 distro maintainers to run once when a package is being created. It finds the
277 optimal Karatsuba number (see the [algorithms manual][7] for more information)
278 for the machine that it is running on.
280 The easiest way to run this script is with `make karatsuba`.
282 If desired, maintainers can also skip running this script because there is a
283 sane default for the Karatsuba number.
289 It is well-tested, fuzzed, and fully standards-compliant (though not certified)
290 with POSIX `bc`. The math has been tested with 40+ million random problems, so
291 it is as correct as I can make it.
293 This `bc` can be used as a drop-in replacement for any existing `bc`. This `bc`
294 is also compatible with MinGW toolchains.
296 In addition, this `bc` is considered complete; i.e., there will be no more
297 releases with additional features. However, it *is* actively maintained, so if
298 any bugs are found, they will be fixed in new releases. Also, additional
299 translations will also be added as they are provided.
303 If I (Gavin D. Howard) get [hit by a bus][27] and future programmers need to
304 handle work themselves, the best place to start is the [Development manual][28].
308 I have developed (using other people's code to start) [`vim` syntax files][17]
309 for this `bc` and `dc`, including the extensions.
313 I have gathered some excellent [`bc` and `dc` libraries][18]. These libraries
314 may prove useful to any serious users.
316 ## Comparison to GNU `bc`
318 This `bc` compares favorably to GNU `bc`.
320 * This `bc` builds natively on Windows.
321 * It has more extensions, which make this `bc` more useful for scripting. (See
322 [Extensions](#extensions).)
323 * This `bc` is a bit more POSIX compliant.
324 * It has a much less buggy parser. The GNU `bc` will give parse errors for what
325 is actually valid `bc` code, or should be. For example, putting an `else` on
326 a new line after a brace can cause GNU `bc` to give a parse error.
327 * This `bc` has fewer crashes.
328 * GNU `bc` calculates the wrong number of significant digits for `length(x)`.
329 * GNU `bc` will sometimes print numbers incorrectly. For example, when running
330 it on the file `tests/bc/power.txt` in this repo, GNU `bc` gets all the right
331 answers, but it fails to wrap the numbers at the proper place when outputting
333 * This `bc` is faster. (See [Performance](#performance).)
337 Because this `bc` packs more than `1` decimal digit per hardware integer, this
338 `bc` is faster than GNU `bc` and can be *much* faster. Full benchmarks can be
339 found at [manuals/benchmarks.md][19].
341 There is one instance where this `bc` is slower: if scripts are light on math.
342 This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but
343 that is because it is more robust. See the [benchmarks][19].
347 Below is a non-comprehensive list of extensions that this `bc` and `dc` have
348 that all others do not.
350 * An extended math library. (See [here][30] for more information.)
351 * A command-line prompt.
352 * Turning on and off digit clamping. (Digit clamping is about how to treat
353 "invalid" digits for a particular base. GNU `bc` uses it, and the BSD `bc`
354 does not. Mine does both.)
355 * A pseudo-random number generator. This includes the ability to set the seed
356 and get reproducible streams of random numbers.
357 * The ability to use stacks for the globals `scale`, `ibase`, and `obase`
358 instead of needing to restore them in *every* function.
359 * The ability to *not* use non-standard keywords. For example, `abs` is a
360 keyword (a built-in function), but if some script actually defines a function
361 called that, it's possible to tell my `bc` to not treat it as a keyword, which
362 will make the script parses correctly.
363 * The ability to turn on and off printing leading zeroes on numbers greater than
364 `-1` and less than `1`.
365 * Outputting in scientific and engineering notation.
366 * Accepting input in scientific and engineering notation.
367 * Passing strings and arrays to the `length()` built-in function. (In `dc`, the
368 `Y` command will do this for arrays, and the `Z` command will do this for both
369 numbers and strings.)
370 * The `abs()` built-in function. (This is the `b` command in `dc`.)
371 * The `is_number()` and `is_string()` built-in functions. (These tell whether a
372 variable is holding a string or a number, for runtime type checking. The
373 commands are `u` and `t` in `dc`.)
374 * For `bc` only, the `divmod()` built-in function for computing a quotient and
375 remainder at the same time.
376 * For `bc` only, the `asciify()` built-in function for converting an array to a
378 * The `$` truncation operator. (It's the same in `bc` and `dc`.)
379 * The `@` "set scale" operator. (It's the same in `bc` and `dc`.)
380 * The decimal shift operators. (`<<` and `>>` in `bc`, `H` and `h` in `dc`.)
381 * Built-in functions or commands to get the max of `scale`, `ibase`, and
383 * The ability to put strings into variables in `bc`. (This always existed in
385 * The `'` command in `dc` for the depth of the execution stack.
386 * The `y` command in `dc` for the depth of register stacks.
387 * Built-in functions or commands to get the value of certain environment
388 variables that might affect execution.
389 * The `stream` keyword to do the same thing as the `P` command in `dc`.
390 * Defined order of evaluation.
391 * Defined exit statuses.
392 * All environment variables other than `POSIXLY_CORRECT`, `BC_ENV_ARGS`, and
394 * The ability for users to define their own defaults for various options during
395 build. (See [here][31] for more information.)
399 To see what algorithms this `bc` uses, see the [algorithms manual][7].
403 Currently, there is no locale support on Windows.
405 Additionally, this `bc` only has support for English (and US English), French,
406 German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales.
407 Patches are welcome for translations; use the existing `*.msg` files in
408 `locales/` as a starting point.
410 In addition, patches for improvements are welcome; the last two messages in
411 Portuguese were made with Google Translate, and the Dutch, Polish, Russian,
412 Japanese, and Chinese locales were all generated with [DeepL][22].
414 The message files provided assume that locales apply to all regions where a
415 language is used, but this might not be true for, e.g., `fr_CA` and `fr_CH`.
416 Any corrections or a confirmation that the current texts are acceptable for
417 those regions would be appreciated, too.
421 Other projects based on this bc are:
423 * [busybox `bc`][8]. The busybox maintainers have made their own changes, so any
424 bugs in the busybox `bc` should be reported to them.
426 * [toybox `bc`][9]. The maintainer has also made his own changes, so bugs in the
427 toybox `bc` should be reported there.
429 * [FreeBSD `bc`][23]. While the `bc` in FreeBSD is kept up-to-date, it is better
430 to [report bugs there][24], as well as [submit patches][25], and the
431 maintainers of the package will contact me if necessary.
435 This `bc` is written in pure ISO C99, using POSIX 2008 APIs with custom Windows
440 This `bc` uses the commit message guidelines laid out in [this blog post][10].
442 ## Semantic Versioning
444 This `bc` uses [semantic versioning][11].
448 This repository is 100% AI-Free code.
452 Items labeled with `(maintainer use only)` are not included in release source
457 .gitignore The git ignore file (maintainer use only).
458 .gitattributes The git attributes file (maintainer use only).
459 bcl.pc.in A template pkg-config file for bcl.
460 configure A symlink to configure.sh to make packaging easier.
461 configure.sh The configure script.
462 LICENSE.md A Markdown form of the BSD 2-clause License.
463 Makefile.in The Makefile template.
464 NEWS.md The changelog.
465 NOTICE.md List of contributors and copyright owners.
469 benchmarks A folder of benchmarks for various aspects of bc performance.
470 gen The bc math library, help texts, and code to generate C source.
471 include All header files.
472 locales Locale files, in .msg format. Patches welcome for translations.
473 manuals Manuals for both programs.
475 scripts A bunch of shell scripts to help with development and building.
477 vs Files needed for the build on Windows.
479 [1]: https://www.gnu.org/software/bc/
481 [5]: ./manuals/build.md
482 [7]: ./manuals/algorithms.md
483 [8]: https://git.busybox.net/busybox/tree/miscutils/bc.c
484 [9]: https://github.com/landley/toybox/blob/master/toys/pending/bc.c
485 [10]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
486 [11]: http://semver.org/
487 [12]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
488 [17]: https://git.gavinhoward.com/gavin/vim-bc
489 [18]: https://git.gavinhoward.com/gavin/bc_libs
490 [19]: ./manuals/benchmarks.md
491 [20]: https://git.gavinhoward.com/gavin/bc
492 [21]: https://gavinhoward.com/2020/04/i-am-moving-away-from-github/
493 [22]: https://www.deepl.com/translator
494 [23]: https://cgit.freebsd.org/src/tree/contrib/bc
495 [24]: https://bugs.freebsd.org/
496 [25]: https://reviews.freebsd.org/
497 [26]: ./manuals/bcl.3.md
498 [27]: https://en.wikipedia.org/wiki/Bus_factor
499 [28]: ./manuals/development.md
500 [29]: https://github.com/gavinhoward/bc
501 [30]: ./manuals/bc/A.1.md#extended-library
502 [31]: ./manuals/build.md#settings