README.md

   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
   8 reasons][21], though GitHub will remain a mirror.***
   9
  10 This 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
  12 flavor of `bc`.
  13
  14 For more information, see this `bc`'s full manual.
  15
  16 This `bc` also includes an implementation of `dc` in the same binary, accessible
  17 via a symbolic link, which implements all FreeBSD and GNU extensions. (If a
  18 standalone `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
  20 functionality is unnecessary.
  21
  22 For more information, see the `dc`'s full manual.
  23
  24 This `bc` is Free and Open Source Software (FOSS). It is offered under the BSD
  25 2-clause License. Full license text may be found in the [`LICENSE.md`][4] file.
  26
  27 ## Prerequisites
  28
  29 This `bc` only requires a C99-compatible compiler and a (mostly) POSIX
  30 2008-compatible system with the XSI (X/Open System Interfaces) option group.
  31
  32 Since POSIX 2008 with XSI requires the existence of a C99 compiler as `c99`, any
  33 POSIX and XSI-compatible system will have everything needed.
  34
  35 Systems 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
  45 Please submit bug reports if this `bc` does not build out of the box on any
  46 system besides Windows. If Windows binaries are needed, they can be found at
  47 [xstatic][6].
  48
  49 ## Build
  50
  51 This `bc` should build unmodified on any POSIX-compliant system.
  52
  53 For more complex build requirements than the ones below, see the
  54 [build manual][5].
  55
  56 ### Pre-built Binaries
  57
  58 It is possible to download pre-compiled binaries for a wide list of platforms,
  59 including Linux- and Windows-based systems, from [xstatic][6]. This link always
  60 points to the latest release of `bc`.
  61
  62 ### Default
  63
  64 For the default build with optimization, use the following commands in the root
  65 directory:
  66
  67 ```
  68 ./configure.sh -O3
  69 make
  70 ```
  71
  72 ### One Calculator
  73
  74 To only build `bc`, use the following commands:
  75
  76 ```
  77 ./configure.sh --disable-dc
  78 make
  79 ```
  80
  81 To only build `dc`, use the following commands:
  82
  83 ```
  84 ./configure.sh --disable-bc
  85 make
  86 ```
  87
  88 ### Debug
  89
  90 For debug builds, use the following commands in the root directory:
  91
  92 ```
  93 ./configure.sh -g
  94 make
  95 ```
  96
  97 ### Install
  98
  99 To install, use the following command:
 100
 101 ```
 102 make install
 103 ```
 104
 105 By default, `bc` and `dc` will be installed in `/usr/local`. For installing in
 106 other 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
 114 When I ran benchmarks with my `bc` compiled under `clang`, it performed much
 115 better than when compiled under `gcc`. I recommend compiling this `bc` with
 116 `clang`.
 117
 118 I also recommend building this `bc` with C11 if you can because `bc` will detect
 119 a C11 compiler and add `_Noreturn` to any relevant function(s).
 120
 121 #### Recommended Optimizations
 122
 123 I wrote this `bc` with Separation of Concerns, which means that there are many
 124 small functions that could be inlined. However, they are often called across
 125 file boundaries, and the default optimizer can only look at the current file,
 126 which means that they are not inlined.
 127
 128 Thus, because of the way this `bc` is built, it will automatically be slower
 129 than other `bc` implementations when running scripts with no math. (My `bc`'s
 130 math is *much* faster, so any non-trivial script should run faster in my `bc`.)
 131
 132 Some, or all, of the difference can be made up with the right optimizations. The
 133 optimizations I recommend are:
 134
 135 1.      `-O3`
 136 2.      `-flto` (link-time optimization)
 137
 138 in that order.
 139
 140 Link-time optimization, in particular, speeds up the `bc` a lot. This is because
 141 when link-time optimization is turned on, the optimizer can look across files
 142 and inline *much* more heavily.
 143
 144 However, 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
 150 By default, non-debug binaries are stripped, but stripping can be disabled with
 151 the `-T` option to `configure.sh`.
 152
 153 #### Using This `bc` as an Alternative
 154
 155 If this `bc` is packaged as an alternative to an already existing `bc` package,
 156 it is possible to rename it in the build to prevent name collision. To prepend
 157 to the name, just run the following:
 158
 159 ```
 160 EXECPREFIX=<some_prefix> ./configure.sh
 161 ```
 162
 163 To append to the name, just run the following:
 164
 165 ```
 166 EXECSUFFIX=<some_suffix> ./configure.sh
 167 ```
 168
 169 If a package maintainer wishes to add both a prefix and a suffix, that is
 170 allowed.
 171
 172 **Note**: The suggested name (and package name) when `bc` is not available is
 173 `bc-gh`.
 174
 175 #### Karatsuba Number
 176
 177 Package and distro maintainers have one tool at their disposal to build this
 178 `bc` in the optimal configuration: `karatsuba.py`.
 179
 180 This script is not a compile-time or runtime prerequisite; it is for package and
 181 distro maintainers to run once when a package is being created. It finds the
 182 optimal Karatsuba number (see the [algorithms manual][7] for more information)
 183 for the machine that it is running on.
 184
 185 The easiest way to run this script is with `make karatsuba`.
 186
 187 If desired, maintainers can also skip running this script because there is a
 188 sane default for the Karatsuba number.
 189
 190 ## Status
 191
 192 This `bc` is robust.
 193
 194 It is well-tested, fuzzed, and fully standards-compliant (though not certified)
 195 with POSIX `bc`. The math has been tested with 40+ million random problems, so
 196 it is as correct as I can make it.
 197
 198 This `bc` can be used as a drop-in replacement for any existing `bc`. This `bc`
 199 is also compatible with MinGW toolchains, though history is not supported on
 200 Windows.
 201
 202 In addition, this `bc` is considered complete; i.e., there will be no more
 203 releases with additional features. However, it *is* actively maintained, so if
 204 any bugs are found, they will be fixed in new releases. Also, additional
 205 translations will also be added as they are provided.
 206
 207 ## Comparison to GNU `bc`
 208
 209 This `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
 226 Because 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
 228 found at [manuals/benchmarks.md][19].
 229
 230 There is one instance where this `bc` is slower: if scripts are light on math.
 231 This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but
 232 that is because it is more robust. See the [benchmarks][19].
 233
 234 ## Algorithms
 235
 236 To see what algorithms this `bc` uses, see the [algorithms manual][7].
 237
 238 ## Locales
 239
 240 Currently, this `bc` only has support for English (and US English), French,
 241 German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales.
 242 Patches are welcome for translations; use the existing `*.msg` files in
 243 `locales/` as a starting point.
 244
 245 In addition, patches for improvements are welcome; the last two messages in
 246 Portuguese were made with Google Translate, and the Dutch, Polish, Russian,
 247 Japanese, and Chinese locales were all generated with [DeepL][22].
 248
 249 The message files provided assume that locales apply to all regions where a
 250 language is used, but this might not be true for, e.g., `fr_CA` and `fr_CH`.
 251 Any corrections or a confirmation that the current texts are acceptable for
 252 those regions would be appreciated, too.
 253
 254 ## Other Projects
 255
 256 Other 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
 270 This `bc` is written in pure ISO C99, using POSIX 2008 APIs.
 271
 272 ## Commit Messages
 273
 274 This `bc` uses the commit message guidelines laid out in [this blog post][10].
 275
 276 ## Semantic Versioning
 277
 278 This `bc` uses [semantic versioning][11].
 279
 280 ## Contents
 281
 282 Items labeled with `(maintainer use only)` are not included in release source
 283 tarballs.
 284
 285 Files:
 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
 306 Folders:
 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/