1# `bc` 2 3[![Coverity Scan Build Status][17]][18] 4 5***WARNING: This project has moved to [https://git.yzena.com/][20] for [these 6reasons][21], though GitHub will remain a mirror.*** 7 8This 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 10flavor of `bc`. 11 12For more information, see this `bc`'s full manual. 13 14This `bc` also includes an implementation of `dc` in the same binary, accessible 15via a symbolic link, which implements all FreeBSD and GNU extensions. (If a 16standalone `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 18functionality is unnecessary. 19 20For more information, see the `dc`'s full manual. 21 22This `bc` is Free and Open Source Software (FOSS). It is offered under the BSD 232-clause License. Full license text may be found in the [`LICENSE.md`][4] file. 24 25## Prerequisites 26 27This `bc` only requires a C99-compatible compiler and a (mostly) POSIX 282008-compatible system with the XSI (X/Open System Interfaces) option group. 29 30Since POSIX 2008 with XSI requires the existence of a C99 compiler as `c99`, any 31POSIX and XSI-compatible system will have everything needed. 32 33Systems that are known to work: 34 35* Linux 36* FreeBSD 37* OpenBSD 38* NetBSD 39* Mac OSX 40* Solaris* (as long as the Solaris version supports POSIX 2008) 41* AIX 42* HP-UX* (except for history) 43 44Please submit bug reports if this `bc` does not build out of the box on any 45system besides Windows. 46 47## Build 48 49This `bc` should build unmodified on any POSIX-compliant system. 50 51For more complex build requirements than the ones below, see the 52[build manual][5]. 53 54### Default 55 56For the default build with optimization, use the following commands in the root 57directory: 58 59``` 60./configure.sh -O3 61make 62``` 63 64### One Calculator 65 66To only build `bc`, use the following commands: 67 68``` 69./configure.sh --disable-dc 70make 71``` 72 73To only build `dc`, use the following commands: 74 75``` 76./configure.sh --disable-bc 77make 78``` 79 80### Debug 81 82For debug builds, use the following commands in the root directory: 83 84``` 85./configure.sh -g 86make 87``` 88 89### Install 90 91To install, use the following command: 92 93``` 94make install 95``` 96 97By default, `bc` and `dc` will be installed in `/usr/local`. For installing in 98other locations, use the `PREFIX` environment variable when running 99`configure.sh` or pass the `--prefix=<prefix>` option to `configure.sh`. See the 100[build manual][5], or run `./configure.sh --help`, for more details. 101 102### Library 103 104This `bc` does provide a way to build a math library with C bindings. This is 105done by the `-a` or `--library` options to `configure.sh`: 106 107``` 108./configure.sh -a 109``` 110 111When building the library, the executables are not built. For more information, 112see the [build manual][5]. 113 114The library API can be found in [`manuals/bcl.3.md`][26] or `man bcl` once the 115library is installed. 116 117The library is built as `bin/libbcl.a`. 118 119### Package and Distro Maintainers 120 121#### Recommended Compiler 122 123When I ran benchmarks with my `bc` compiled under `clang`, it performed much 124better than when compiled under `gcc`. I recommend compiling this `bc` with 125`clang`. 126 127I also recommend building this `bc` with C11 if you can because `bc` will detect 128a C11 compiler and add `_Noreturn` to any relevant function(s). 129 130#### Recommended Optimizations 131 132I wrote this `bc` with Separation of Concerns, which means that there are many 133small functions that could be inlined. However, they are often called across 134file boundaries, and the default optimizer can only look at the current file, 135which means that they are not inlined. 136 137Thus, because of the way this `bc` is built, it will automatically be slower 138than other `bc` implementations when running scripts with no math. (My `bc`'s 139math is *much* faster, so any non-trivial script should run faster in my `bc`.) 140 141Some, or all, of the difference can be made up with the right optimizations. The 142optimizations I recommend are: 143 1441. `-O3` 1452. `-flto` (link-time optimization) 146 147in that order. 148 149Link-time optimization, in particular, speeds up the `bc` a lot. This is because 150when link-time optimization is turned on, the optimizer can look across files 151and inline *much* more heavily. 152 153However, I recommend ***NOT*** using `-march=native`. Doing so will reduce this 154`bc`'s performance, at least when building with link-time optimization. See the 155[benchmarks][19] for more details. 156 157#### Stripping Binaries 158 159By default, non-debug binaries are stripped, but stripping can be disabled with 160the `-T` option to `configure.sh`. 161 162#### Using This `bc` as an Alternative 163 164If this `bc` is packaged as an alternative to an already existing `bc` package, 165it is possible to rename it in the build to prevent name collision. To prepend 166to the name, just run the following: 167 168``` 169EXECPREFIX=<some_prefix> ./configure.sh 170``` 171 172To append to the name, just run the following: 173 174``` 175EXECSUFFIX=<some_suffix> ./configure.sh 176``` 177 178If a package maintainer wishes to add both a prefix and a suffix, that is 179allowed. 180 181**Note**: The suggested name (and package name) when `bc` is not available is 182`bc-gh`. 183 184#### Karatsuba Number 185 186Package and distro maintainers have one tool at their disposal to build this 187`bc` in the optimal configuration: `karatsuba.py`. 188 189This script is not a compile-time or runtime prerequisite; it is for package and 190distro maintainers to run once when a package is being created. It finds the 191optimal Karatsuba number (see the [algorithms manual][7] for more information) 192for the machine that it is running on. 193 194The easiest way to run this script is with `make karatsuba`. 195 196If desired, maintainers can also skip running this script because there is a 197sane default for the Karatsuba number. 198 199## Status 200 201This `bc` is robust. 202 203It is well-tested, fuzzed, and fully standards-compliant (though not certified) 204with POSIX `bc`. The math has been tested with 40+ million random problems, so 205it is as correct as I can make it. 206 207This `bc` can be used as a drop-in replacement for any existing `bc`. This `bc` 208is also compatible with MinGW toolchains, though history is not supported on 209Windows. 210 211In addition, this `bc` is considered complete; i.e., there will be no more 212releases with additional features. However, it *is* actively maintained, so if 213any bugs are found, they will be fixed in new releases. Also, additional 214translations will also be added as they are provided. 215 216## Comparison to GNU `bc` 217 218This `bc` compares favorably to GNU `bc`. 219 220* It has more extensions, which make this `bc` more useful for scripting. 221* This `bc` is a bit more POSIX compliant. 222* It has a much less buggy parser. The GNU `bc` will give parse errors for what 223 is actually valid `bc` code, or should be. For example, putting an `else` on 224 a new line after a brace can cause GNU `bc` to give a parse error. 225* This `bc` has fewer crashes. 226* GNU `bc` calculates the wrong number of significant digits for `length(x)`. 227* GNU `bc` will sometimes print numbers incorrectly. For example, when running 228 it on the file `tests/bc/power.txt` in this repo, GNU `bc` gets all the right 229 answers, but it fails to wrap the numbers at the proper place when outputting 230 to a file. 231* This `bc` is faster. (See [Performance](#performance).) 232 233### Performance 234 235Because this `bc` packs more than `1` decimal digit per hardware integer, this 236`bc` is faster than GNU `bc` and can be *much* faster. Full benchmarks can be 237found at [manuals/benchmarks.md][19]. 238 239There is one instance where this `bc` is slower: if scripts are light on math. 240This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but 241that is because it is more robust. See the [benchmarks][19]. 242 243## Algorithms 244 245To see what algorithms this `bc` uses, see the [algorithms manual][7]. 246 247## Locales 248 249Currently, this `bc` only has support for English (and US English), French, 250German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales. 251Patches are welcome for translations; use the existing `*.msg` files in 252`locales/` as a starting point. 253 254In addition, patches for improvements are welcome; the last two messages in 255Portuguese were made with Google Translate, and the Dutch, Polish, Russian, 256Japanese, and Chinese locales were all generated with [DeepL][22]. 257 258The message files provided assume that locales apply to all regions where a 259language is used, but this might not be true for, e.g., `fr_CA` and `fr_CH`. 260Any corrections or a confirmation that the current texts are acceptable for 261those regions would be appreciated, too. 262 263## Other Projects 264 265Other projects based on this bc are: 266 267* [busybox `bc`][8]. The busybox maintainers have made their own changes, so any 268 bugs in the busybox `bc` should be reported to them. 269 270* [toybox `bc`][9]. The maintainer has also made his own changes, so bugs in the 271 toybox `bc` should be reported there. 272 273* [FreeBSD `bc`][23]. While the `bc` in FreeBSD is kept up-to-date, it is better 274 to [report bugs there][24], as well as [submit patches][25], and the 275 maintainers of the package will contact me if necessary. 276 277## Language 278 279This `bc` is written in pure ISO C99, using POSIX 2008 APIs. 280 281## Commit Messages 282 283This `bc` uses the commit message guidelines laid out in [this blog post][10]. 284 285## Semantic Versioning 286 287This `bc` uses [semantic versioning][11]. 288 289## Contents 290 291Items labeled with `(maintainer use only)` are not included in release source 292tarballs. 293 294Files: 295 296 .gitignore The git ignore file (maintainer use only). 297 configure A symlink to configure.sh to make packaging easier. 298 configure.sh The configure script. 299 functions.sh A script with functions used by other scripts. 300 install.sh Install script. 301 karatsuba.py Script to find the optimal Karatsuba number. 302 LICENSE.md A Markdown form of the BSD 2-clause License. 303 link.sh A script to link dc to bc. 304 locale_install.sh A script to install locales, if desired. 305 locale_uninstall.sh A script to uninstall locales. 306 Makefile.in The Makefile template. 307 manpage.sh Script to generate man pages from markdown files. 308 NOTICE.md List of contributors and copyright owners. 309 RELEASE.md A checklist for making a release (maintainer use only). 310 release.sh A script to test for release (maintainer use only). 311 safe-install.sh Safe install script from musl libc. 312 313Folders: 314 315 gen The bc math library, help texts, and code to generate C source. 316 include All header files. 317 locales Locale files, in .msg format. Patches welcome for translations. 318 manuals Manuals for both programs. 319 src All source code. 320 tests All tests. 321 322[1]: https://www.gnu.org/software/bc/ 323[4]: ./LICENSE.md 324[5]: ./manuals/build.md 325[7]: ./manuals/algorithms.md 326[8]: https://git.busybox.net/busybox/tree/miscutils/bc.c 327[9]: https://github.com/landley/toybox/blob/master/toys/pending/bc.c 328[10]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html 329[11]: http://semver.org/ 330[12]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html 331[17]: https://img.shields.io/coverity/scan/16609.svg 332[18]: https://scan.coverity.com/projects/gavinhoward-bc 333[19]: ./manuals/benchmarks.md 334[20]: https://git.yzena.com/gavin/bc 335[21]: https://gavinhoward.com/2020/04/i-am-moving-away-from-github/ 336[22]: https://www.deepl.com/translator 337[23]: https://cgit.freebsd.org/src/tree/contrib/bc 338[24]: https://bugs.freebsd.org/ 339[25]: https://reviews.freebsd.org/ 340[26]: ./manuals/bcl.3.md 341
