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