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