contrib/bc/README.md

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