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