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