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
  43 Please submit bug reports if this `bc` does not build out of the box on any
  44 system besides Windows. If Windows binaries are needed, they can be found at
  45 [xstatic][6].
  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 ### Pre-built Binaries
  55
  56 It is possible to download pre-compiled binaries for a wide list of platforms,
  57 including Linux- and Windows-based systems, from [xstatic][6]. This link always
  58 points to the latest release of `bc`.
  59
  60 ### Default
  61
  62 For the default build with optimization, use the following commands in the root
  63 directory:
  64
  65 ```
  66 ./configure.sh -O3
  67 make
  68 ```
  69
  70 ### One Calculator
  71
  72 To only build `bc`, use the following commands:
  73
  74 ```
  75 ./configure.sh --disable-dc
  76 make
  77 ```
  78
  79 To only build `dc`, use the following commands:
  80
  81 ```
  82 ./configure.sh --disable-bc
  83 make
  84 ```
  85
  86 ### Debug
  87
  88 For debug builds, use the following commands in the root directory:
  89
  90 ```
  91 ./configure.sh -g
  92 make
  93 ```
  94
  95 ### Install
  96
  97 To install, use the following command:
  98
  99 ```
 100 make install
 101 ```
 102
 103 By default, `bc` and `dc` will be installed in `/usr/local`. For installing in
 104 other 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
 110 This `bc` does provide a way to build a math library with C bindings. This is
 111 done by the `-a` or `--library` options to `configure.sh`:
 112
 113 ```
 114 ./configure.sh -a
 115 ```
 116
 117 When building the library, the executables are not built. For more information,
 118 see the [build manual][5].
 119
 120 The library API can be found in [`manuals/bcl.3.md`][26] or `man bcl` once the
 121 library is installed.
 122
 123 The library is built as `bin/libbcl.a`.
 124
 125 ### Package and Distro Maintainers
 126
 127 #### Recommended Compiler
 128
 129 When I ran benchmarks with my `bc` compiled under `clang`, it performed much
 130 better than when compiled under `gcc`. I recommend compiling this `bc` with
 131 `clang`.
 132
 133 I also recommend building this `bc` with C11 if you can because `bc` will detect
 134 a C11 compiler and add `_Noreturn` to any relevant function(s).
 135
 136 #### Recommended Optimizations
 137
 138 I wrote this `bc` with Separation of Concerns, which means that there are many
 139 small functions that could be inlined. However, they are often called across
 140 file boundaries, and the default optimizer can only look at the current file,
 141 which means that they are not inlined.
 142
 143 Thus, because of the way this `bc` is built, it will automatically be slower
 144 than other `bc` implementations when running scripts with no math. (My `bc`'s
 145 math is *much* faster, so any non-trivial script should run faster in my `bc`.)
 146
 147 Some, or all, of the difference can be made up with the right optimizations. The
 148 optimizations I recommend are:
 149
 150 1.      `-O3`
 151 2.      `-flto` (link-time optimization)
 152
 153 in that order.
 154
 155 Link-time optimization, in particular, speeds up the `bc` a lot. This is because
 156 when link-time optimization is turned on, the optimizer can look across files
 157 and inline *much* more heavily.
 158
 159 However, 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
 165 By default, non-debug binaries are stripped, but stripping can be disabled with
 166 the `-T` option to `configure.sh`.
 167
 168 #### Using This `bc` as an Alternative
 169
 170 If this `bc` is packaged as an alternative to an already existing `bc` package,
 171 it is possible to rename it in the build to prevent name collision. To prepend
 172 to the name, just run the following:
 173
 174 ```
 175 EXECPREFIX=<some_prefix> ./configure.sh
 176 ```
 177
 178 To append to the name, just run the following:
 179
 180 ```
 181 EXECSUFFIX=<some_suffix> ./configure.sh
 182 ```
 183
 184 If a package maintainer wishes to add both a prefix and a suffix, that is
 185 allowed.
 186
 187 **Note**: The suggested name (and package name) when `bc` is not available is
 188 `bc-gh`.
 189
 190 #### Karatsuba Number
 191
 192 Package and distro maintainers have one tool at their disposal to build this
 193 `bc` in the optimal configuration: `karatsuba.py`.
 194
 195 This script is not a compile-time or runtime prerequisite; it is for package and
 196 distro maintainers to run once when a package is being created. It finds the
 197 optimal Karatsuba number (see the [algorithms manual][7] for more information)
 198 for the machine that it is running on.
 199
 200 The easiest way to run this script is with `make karatsuba`.
 201
 202 If desired, maintainers can also skip running this script because there is a
 203 sane default for the Karatsuba number.
 204
 205 ## Status
 206
 207 This `bc` is robust.
 208
 209 It is well-tested, fuzzed, and fully standards-compliant (though not certified)
 210 with POSIX `bc`. The math has been tested with 40+ million random problems, so
 211 it is as correct as I can make it.
 212
 213 This `bc` can be used as a drop-in replacement for any existing `bc`. This `bc`
 214 is also compatible with MinGW toolchains, though history is not supported on
 215 Windows.
 216
 217 In addition, this `bc` is considered complete; i.e., there will be no more
 218 releases with additional features. However, it *is* actively maintained, so if
 219 any bugs are found, they will be fixed in new releases. Also, additional
 220 translations will also be added as they are provided.
 221
 222 ## Comparison to GNU `bc`
 223
 224 This `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
 241 Because 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
 243 found at [manuals/benchmarks.md][19].
 244
 245 There is one instance where this `bc` is slower: if scripts are light on math.
 246 This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but
 247 that is because it is more robust. See the [benchmarks][19].
 248
 249 ## Algorithms
 250
 251 To see what algorithms this `bc` uses, see the [algorithms manual][7].
 252
 253 ## Locales
 254
 255 Currently, this `bc` only has support for English (and US English), French,
 256 German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales.
 257 Patches are welcome for translations; use the existing `*.msg` files in
 258 `locales/` as a starting point.
 259
 260 In addition, patches for improvements are welcome; the last two messages in
 261 Portuguese were made with Google Translate, and the Dutch, Polish, Russian,
 262 Japanese, and Chinese locales were all generated with [DeepL][22].
 263
 264 The message files provided assume that locales apply to all regions where a
 265 language is used, but this might not be true for, e.g., `fr_CA` and `fr_CH`.
 266 Any corrections or a confirmation that the current texts are acceptable for
 267 those regions would be appreciated, too.
 268
 269 ## Other Projects
 270
 271 Other 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
 285 This `bc` is written in pure ISO C99, using POSIX 2008 APIs.
 286
 287 ## Commit Messages
 288
 289 This `bc` uses the commit message guidelines laid out in [this blog post][10].
 290
 291 ## Semantic Versioning
 292
 293 This `bc` uses [semantic versioning][11].
 294
 295 ## Contents
 296
 297 Items labeled with `(maintainer use only)` are not included in release source
 298 tarballs.
 299
 300 Files:
 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
 319 Folders:
 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