Lines Matching +full:- +full:- +full:exclude +full:- +full:unreachable +full:- +full:branches
6 bus][1]. In other words, it's meant to make the [bus factor][1] a non-issue.
25 and C. They both are arbitrary-precision command-line calculators with their own
30 In addition, it is also possible to build the arbitrary-precision math as a
58 This project became a passion project for me, and I continued. In mid-2019,
64 about things like fuzzing, [`scan-build`][19], [valgrind][20],
150 pseudo-random number generator (for the same seed).
183 * Pseudo-Random Number Generator (see [`include/rand.h`][37]).
213 1. High-level requirements
214 2. Low-level requirements
215 3. High-level implementation
216 4. Low-level implementation
233 alias makej='make -j16'
235 alias mcmakej='make clean && make -j16'
236 alias bcdebug='CPPFLAGS="-DBC_DEBUG_CODE=1" CFLAGS="-Weverything -Wno-padded \
237 -Wno-switch-enum -Wno-format-nonliteral -Wno-cast-align \
238 -Wno-unreachable-code-return -Wno-missing-noreturn \
239 -Wno-disabled-macro-expansion -Wno-unreachable-code -Wall -Wextra \
240 -pedantic -std=c99" ./configure.sh'
241 alias bcconfig='CFLAGS="-Weverything -Wno-padded -Wno-switch-enum \
242 -Wno-format-nonliteral -Wno-cast-align -Wno-unreachable-code-return \
243 -Wno-missing-noreturn -Wno-disabled-macro-expansion -Wno-unreachable-code \
244 -Wall -Wextra -pedantic -std=c99" ./configure.sh'
245 alias bcnoassert='CPPFLAGS="-DNDEBUG" CFLAGS="-Weverything -Wno-padded \
246 -Wno-switch-enum -Wno-format-nonliteral -Wno-cast-align \
247 -Wno-unreachable-code-return -Wno-missing-noreturn \
248 -Wno-disabled-macro-expansion -Wno-unreachable-code -Wall -Wextra \
249 -pedantic -std=c99" ./configure.sh'
250 alias bcdebugnoassert='CPPFLAGS="-DNDEBUG -DBC_DEBUG_CODE=1" \
251 CFLAGS="-Weverything -Wno-padded -Wno-switch-enum -Wno-format-nonliteral \
252 -Wno-cast-align -Wno-unreachable-code-return -Wno-missing-noreturn \
253 -Wno-disabled-macro-expansion -Wno-unreachable-code -Wall -Wextra \
254 -pedantic -std=c99" ./configure.sh'
261 command-line.
279 export BC_ENV_ARGS="-l $HOME/.bcrc"
285 run `bc -s` on my `$HOME/.bcrc`.
301 t-=s
303 t-=m
305 t-=h
360 existing `.clang-format` file. More precisely, the style is whatever is output
391 * If single-line bodies are on a separate line from their headers, and the
417 Functions are documented with Doxygen-style doc comments. Functions that appear
437 Turing-complete programming language. It's a terrible one, but it works.
451 1. It processes command-line arguments and figure out what the user wants to
454 3. One-by-one, it replaces placeholders (in [`Makefile.in`][70]) of the form
485 [POSIX `make`][74]-compatible `Makefile` (minus the placeholders). Here are a
604 A text file containing the text displayed for `bc -h` or `bc --help`.
606 This text just contains the command-line options and a short summary of the
617 A text file containing the text displayed for `dc -h` or `dc --help`.
619 This text just contains the command-line options and a short summary of the
648 First, all constants must be one digit. This is because otherwise, multi-digit
650 This does not happen with single-digit numbers because they are guaranteed to be
657 to set it with a single-digit number and beware the snare below...
660 from any function in the library. This is because without the `-g` option,
668 must not use *any* extensions. It has to work when users use the `-s` or `-w`
737 This file is the API for processing command-line arguments.
741 This header is the API for `bc`-only items. This includes the `bc_main()`
742 function and the `bc`-specific lexing and parsing items.
758 that it has platform-specific fixes for Windows. (If the fixes were not in this
765 This header is the API for `dc`-only items. This includes the `dc_main()`
766 function and the `dc`-specific lexing and parsing items.
783 This header is for `bc`'s implementation of command-line editing/history, which
784 is based on a [UTF-8-aware fork][28] of [`linenoise`][29].
786 For more information, see the [Command-Line History][189] section.
823 This header is the API for parsing command-line arguments.
826 to process the command-line arguments into global data *after* they have already
828 parses the command-line arguments, and [`args.h`][31] turns that parsed data
834 adapted a [public-domain option parsing library][34] to do the job instead. And
862 This header defines the API for the [pseudo-random number generator
865 The PRNG only generates fixed-size integers. The magic of generating random
885 * Compiler-specific fixes.
886 * Platform-specific fixes.
1082 collection mechanism of the [`BcNum` caching][96] works. It has been little-used
1106 #### `exec-install.sh`
1237 meant for outside use. This means that some non-POSIX utilities can be used,
1250 A script to test `bc`'s command-line expression parsing code, which, while
1269 previously-installed version of this `bc` and `dc`.
1272 `bc` using `./scripts/fuzz_prep.sh -a`, and then run it under this script. Any
1284 report mode. One-by-one, it will go through the "checklist," the list of failed
1307 alone for 32-bit.
1318 #### `safe-install.sh`
1347 [`dc_parse.c`][46]) where possible because it is cleaner to exclude an entire
1356 Code for processing command-line arguments.
1424 The code for `bc`'s implementation of command-line editing/history, which is
1425 based on a [UTF-8-aware fork][28] of [`linenoise`][29].
1427 For more information, see the [Command-Line History][189] section.
1471 The code for all of the arbitrary-precision [numbers][177] and [math][178] in
1478 The code for parsing command-line options.
1496 The code for the [pseudo-random number generator (PRNG)][179] and the special
1499 The PRNG only generates fixed-size integers. The magic of generating random
1549 The script to run the file-based error tests in `tests/<calculator>/errors/` for
1557 The script to run the line-based error tests in `tests/<calculator>/errors.txt`
1576 This script also re-runs the test three times if it fails. This is because
1881 the Karatsuba multiplication algorithm switches to brute-force
1903 disabled, but both `BC_ENABLED` and `DC_ENABLED` must be non-zero.
1954 : If this macro expands to a non-zero integer, then `bc` is built with *a lot*
1991 make -j<cores> test
1998 I have even tried as much as possible, to put longer-running tests near the
2024 are generated by a GNU-compatible `bc` or `dc`. See the [Generated Tests][143]
2033 and its results are generated by a GNU-compatible `bc` or `dc`. See the
2036 To add a non-generated standard test, do the following:
2182 Single-letter numbers always be set to the same value, regardless of
2225 classify them, but it's really testing multi-line numbers.
2261 : Tests the pseudo-random number generator and its special stack handling.
2288 : Tests the `is_number()` built-in function.
2292 : Tests the `is_number()` built-in function.
2300 : Tests the line-by-line behavior of `bc` with regards to `quit` in a function
2305 : Tests the line-by-line behavior of `bc` with regards to `quit`.
2309 : Tests the behavior of `bc` with a `quit` after a single-line loop.
2313 : Tests the behavior of `bc` with a `quit` after a single-line loop and a
2427 : Tests the pseudo-random number generator and its special stack handling.
2431 : Tests the `is_number()` built-in function (the `u` command).
2435 : Tests the `is_number()` built-in function (the `t` command).
2463 `-g` and `--global-stacks` flags. This means that all of the script tests for
2464 `bc` are written assuming the `-g` flag was given on the command-line
2616 machine-generated (by [AFL++][125]) ones.
2638 are run by [`tests/errors.sh`][226]. It reads them line-by-line and shoves the
2647 command-line.
2651 Is it a simple one-liner, and you don't care if it's tested through a file?
2659 command-line, or the error requires multiple lines to reproduce, then put the
2668 The `stdin` tests specifically test the lexing and parsing of multi-line
2689 other types of tests. They usually include things like command-line parsing and
2725 I have added as many tests as I could to cover as many lines and branches as
2731 use parallel execution with `make -j<cores> test_history`.
2757 Yes, the error code is not a success all the time. This is because of the UTF-8
2758 tests; `bc` gives a fatal error on any non-ASCII data because ASCII is all `bc`
2788 Instead, the tests depend on the existence of a GNU-compatible `bc` in the
2791 If [`configure.sh`][69] was run with the `-G` argument, which disables generated
2794 GNU-compatible `bc` installed.
2799 For example, `bc`'s test suite will automatically use a GNU-compatible `bc` to
2823 GNU-compatible `bc` is used to generate the `<test>.txt` results file.
2842 In addition, there are more fine-grained targets available:
2986 CC=gcc ./configure -gO3 -c
2987 make -j<cores>
2991 Note that `make coverage` does not have a `-j<cores>` part; it cannot be run in
2998 If you see lines or branches that you think you could hit with a manual
3012 make -j<cores>
3021 make -j<cores>
3022 make -j<cores> test
3034 CFLAGS="-fsanitize=<sanitizer> ./configure -gO3 -m
3035 make -j<cores>
3036 make -j<cores> test
3044 CFLAGS="-fsanitize=undefined" ./configure -gO0 -m
3045 make -j<cores>
3046 make -j<cores> test
3054 ./configure -gO3 -v
3055 make -j<cores>
3056 make -j<cores> test
3077 1. No `bash`-isms.
3079 3. Only command-line options defined in the POSIX standard for POSIX utilities
3104 ### Maintainer-Only Scripts
3152 POSIX-compatible locales are terrible.
3156 First, `gencat` does not work for generating cross-compilation. In other words,
3157 it does not generate machine-portable files. There's nothing I can do about
3200 [`scan-build`][19]. I only use it in debug mode because I have to add some
3205 function to be initialized. [`scan-build`][19] misses that fact, so I
3206 pre-initialize such locals to prevent the warnings.
3208 To run `scan-build`, do the following:
3212 scan-build make
3215 `scan-build` will print its warnings to `stdout`.
3277 stability: the pseudo-random number generator *must* start with *exactly* the
3305 assumes the existence of `afl-clang-lto` in the `$PATH`, but if that exists, it
3306 automatically configures and builds `bc` with a fuzz-ideal build.
3308 A fuzz-ideal build has several things:
3310 * `afl-clang-lto` as the compiler. (See [AFL++ Quickstart][129].)
3312 * Full optimization (including [Link-Time Optimization][126]), for performance.
3317 There is one big thing that a fuzz-ideal build does *not* have: it does not use
3323 However, to add to [`scripts/fuzz_prep.sh`][119] making a fuzz-ideal build, in
3421 code to the binary to help it know when certain branches are taken.
3459 to use with varying command-line arguments, which was needed for testing `bc`'s
3460 command-line expression parsing code, and [AFL++][125] is best when testing
3467 not had to touch the command-line expression parsing code since.
3489 ./scripts/fuzz_prep.sh -a
3490 ./scripts/afl.py --asan bc1
3491 ./scripts/afl.py --asan bc2
3492 ./scripts/afl.py --asan bc3
3493 ./scripts/afl.py --asan dc
3499 These commands build an [ASan][21]-enabled build of `bc` and `dc` and then they
3524 POSIX mode is `bc`-only.
3527 These modes are designed to help users write POSIX-compatible `bc` scripts.
3531 Standard Mode is activated with the `-s` or `--standard` flags.
3538 Warning Mode is activated with the `-w` or `--warn` flags.
3562 ### [Async-Signal-Safe][115] Signal Handling
3565 `bc` is, by and large, CPU-bound. This has several consequences, but the biggest
3575 Alternatively, I/O bound programs can use the [self-pipe trick][199].
3605 Other than that, the rest of the interrupt-based implementation is best
3610 First, signal handlers can only call [async-signal-safe][115] functions.
3623 Vectors and numbers needed special consideration with the interrupt-based signal
3630 be able to interrupt a non-[async-signal-safe][115] function like `malloc()` and
3668 At first glance, it may seem like putting asserts for pointers being non-`NULL`
3671 how many branches it covers. If there are too many `assert()`'s, it may think
3806 for general-purpose allocators to handle efficiently.
3823 slab is put into the vacated spot. This ensures that a non-special slab is
3826 ### Command-Line History
3831 It sucked, and the biggest reason why was because of the lack of command-line
3834 At first, I just dealt with it, not knowing how command-line history might be
3837 Eventually, I caved and attempted to adapt [`linenoise-mob`][28], which I had
3843 Understanding command-line history in `bc` is really about understanding VT-100
3847 adaptation to make the command-line history implementation perfect for `bc`
3853 all of that, it does not have at least one feature: multi-line pasting from the
3911 It turns out that what I needed was a [async-signal-safe][115] form of what
3922 2. While `longjmp()` is required to be [async-signal-safe][115], if it is
3923 invoked by a signal handler that interrupted a non-[async-signal-safe][115]
3938 sig_atomic_t`. (For more information, see the [Async-Signal-Safe Signal
3940 async-signal-safe, they first need to use `BC_SIG_LOCK` to lock signals, and
3943 Code also need to do this for all global, non-atomic mutation, which means that
3957 In this way, C++-style exceptions were implemented in pure C. Not fun, but it
3972 all of the buffered I/O API is basically non-[async-signal-safe][115].
3981 easily-parsable form.
4010 just processes command-line arguments after they are parsed by
4045 [Shunting-Yard Algorithm][109] is designed to generate [Reverse Polish
4080 |------------|-------|--------------------------------------------|
4094 | `-` | x | Subtraction |
4097 | `0-9` | x | Numbers |
4105 | `A-F` | x | Numbers |
4175 *always* at a REPL (Read-Eval-Print Loop). `bc` is, first and foremost, an
4205 `bc`'s language is Turing-complete. That means that code needs the ability to
4224 "Cond" labels are so-called because they are used by conditionals.
4230 well-known. Cond labels are easy.
4239 "Exit" labels are so-called because they are used by code "exiting" out of `if`
4268 That extra work is called the [Shunting-Yard algorithm][109], and the form it
4272 [Shunting-Yard algorithm][109]. Go do that before you read on.
4276 In `bc`, the [Shunting-Yard algorithm][109] is implemented with bytecode as the
4441 little-endian order.
4538 * To seed the pseudo-random number generator.
4574 In order to do arbitrary-precision math, as `bc` must do, there must be some way
4575 of representing arbitrary-precision numbers. `BcNum` in [`include/num.h`][184]
4579 applied to arbitrary-precision numbers. It means one piece of the number. It can
4601 between -1 and 1).
4620 scale + (BC_BASE_DIGS - 1) / BC_BASE_DIGS == rdx >> 1
4624 64-bit systems and 4 on other systems.)
4640 little-endian order. This means that the last decimal places are in the limb
4641 stored at index 0, and the most significant digits are stored at index `len-1`.
4660 equal to -1.
4661 * `(rdx >> 1) < len`: the number is greater than -1 and less than 1, not
4691 * Use the digit as-is, multiplying it by the `ibase` to the power of the digit's
4697 It is possible to switch between the two with the `-c` and `-C` command-line
4731 ### Pseudo-Random Number Generator
4734 manpages about the pseudo-random number generator (PRNG) first; that will help
4739 cryptographically secure PRNG available via command-line, usually
4747 On top of that, `bc` is an arbitrary-precision calculator; if I made it able to
4761 I could, of course, put the entire 255 bits into one massive arbitrary-precision
4799 3. Divide the seed by `2^128` with a `scale` of 128. (For 32-bit systems,
4803 Likewise, the algorithm to convert from a user-supplied number to a seed is:
4812 #### Generating Arbitrary-Precision Numbers
4828 Besides building `bc` in debug mode with the `-g` flag to [`configure.sh`][69],
4829 programmers can also add `-DBC_DEBUG_CODE=1` to the `CFLAGS`. This will enable
4847 First, users can probably use [profile-guided optimization][217] to optimize
4858 `BC_LIKELY`; I just added them to also document branches that lead to error
4872 Also, as stated in the [build manual][219], link-time optimization is excellent
4908 statically-allocated stack (it's just a global array with a set size). Then,
4934 Even the [pseudo-random number generator][179] is included, with extra support
4947 This is because `bcl` uses thread-specific data to store the "globals" for each
4985 The encoding of errors is this: if an error happens, the value `0-error` is
4987 `0-num_errors` is an error.
5000 [5]: ./bc/A.1.md#standard-library
5002 [7]: ./bc/A.1.md#extended-library
5003 [8]: #libbc-2
5006 [11]: https://gavinhoward.com/2019/12/values-for-yao/
5007 [12]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf
5008 [13]: ./build.md#cross-compiling
5014 [19]: https://clang-analyzer.llvm.org/scan-build.html
5017 [22]: https://gavinhoward.com/2019/11/finishing-software/
5023 [28]: https://github.com/rain-1/linenoise-mob
5027 [32]: ../NEWS.md#3-0-0
5071 [76]: ##posix-shell-scripts
5074 [79]: #bc-1
5075 [80]: #dc-1
5076 [81]: ./build.md#build-type
5077 [82]: #fuzzing-1
5080 [85]: #locales-1
5081 [86]: #manuals-1
5091 [96]: #caching-of-numbers
5092 [97]: #error-handling
5104 [109]: https://en.wikipedia.org/wiki/Shunting-yard_algorithm
5105 [110]: #bc-parsing
5109 [114]: #custom-io
5118 [123]: https://tmuxp.git-pull.com/
5119 [124]: #test-suite
5121 [126]: #link-time-optimization
5122 [127]: #fuzzing-performance
5124 [129]: #afl-quickstart
5127 [132]: https://git.gavinhoward.com/gavin/vim-bc
5133 [138]: #test-suite-portability
5136 [141]: #group-tests
5137 [142]: #build-system
5138 [143]: #generated-tests
5139 [144]: #benchmarks-1
5141 [146]: #test-coverage
5142 [147]: #integration-with-the-build-system
5143 [148]: #test-scripts
5144 [149]: #standard-tests
5145 [150]: #script-tests
5146 [151]: #error-tests
5147 [152]: #stdin-tests
5148 [153]: #read-tests
5149 [154]: #other-tests
5150 [155]: #history-tests
5152 [157]: #bcl-test
5155 [160]: #addresssanitizer-and-friends
5156 [161]: #bc-2
5157 [162]: #dc-2
5158 [163]: #alltxt-1
5162 [167]: #alltxt-3
5163 [168]: #errorstxt-1
5164 [169]: #scripts-1
5165 [170]: #scripts-2
5166 [171]: #alltxt-2
5167 [172]: #alltxt-4
5168 [173]: #async-signal-safe-signal-handling
5173 [178]: #math-style
5174 [179]: #pseudo-random-number-generator
5182 [187]: #slabs-and-slab-vectors
5183 [188]: ./build.md#extra-math
5184 [189]: #command-line-history
5186 [191]: #linux-timeconstbc-script
5189 [194]: https://www.valgrind.org/docs/manual/mc-manual.html
5192 [197]: https://clang-analyzer.llvm.org/
5193 [198]: https://unix.stackexchange.com/questions/253349/eintr-is-there-a-rationale-behind-it
5195 [200]: https://skarnet.org/cgi-bin/archive.cgi?2:mss:1607:201701:dfblejammjllfkggpcph
5196 [201]: https://slembcke.github.io/2020/10/12/CustomAllocators.html#1-slab-allocator
5209 [214]: https://gmplib.org/manual/Nomenclature-and-Types
5211 [216]: #main-and-read-functions
5212 [215]: https://www.pcg-random.org/
5213 [216]: https://lemire.me/blog/2017/08/22/testing-non-cryptographic-random-number-generators-my-resu…
5214 [217]: https://en.wikipedia.org/wiki/Profile-guided_optimization
5215 [218]: https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005fexpect
5219 [222]: https://www.freebsd.org/cgi/man.cgi?query=ministat&apropos=0&sektion=0&manpath=FreeBSD+13.0-…