Lines Matching +full:storage +full:- +full:repo +full:- +full:branch +full:- +full:coverage
6 bus][1]. In other words, it's meant to make the [bus factor][1] a non-issue.
15 the documentation can be closest to the part of the repo where it is actually
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).
169 other part of this repo.
183 * Pseudo-Random Number Generator (see [`include/rand.h`][37]).
207 7. Repo structure.
213 1. High-level requirements
214 2. Low-level requirements
215 3. High-level implementation
216 4. Low-level implementation
226 * A [repo of `bc` and `dc` scripts][133].
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
415 ## Repo Structure
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.
963 For the reason why I check generated data into the repo, see
1082 collection mechanism of the [`BcNum` caching][96] works. It has been little-used
1106 #### `exec-install.sh`
1228 3. Copies the repo to a temp directory.
1237 meant for outside use. This means that some non-POSIX utilities can be used,
1242 directory of the repo, exactly as Windows generated them. If they are not there,
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`
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
1822 * `make clean_coverage` cleans the generated coverage files for the [test
1823 suite][124]'s [code coverage][146] capabilities. It has no prerequisites. This
1824 is useful if the code coverage tools are giving errors.
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
2708 repo is under a BSD license.
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:
2979 ### Test Coverage
2981 In order to get test coverage information, you need `gcc`, `gcov`, and `gcovr`.
2986 CC=gcc ./configure -gO3 -c
2987 make -j<cores>
2988 make coverage
2991 Note that `make coverage` does not have a `-j<cores>` part; it cannot be run in
2995 `index.html` file in the root directory of the repo. From there, you can explore
2996 all of the coverage results.
3005 and the coverage output will be updated.
3007 If you want to rerun `make coverage`, you must do a `make clean` and build
3012 make -j<cores>
3013 make coverage
3021 make -j<cores>
3022 make -j<cores> test
3026 and that will generate coverage output correctly.
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
3423 Then, when fuzzing, it uses that branch information to generate information
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`
3670 `assert()` is a branch, and [AFL++][125] rates its own effectiveness based on
3728 By the way, `len` is different from `cap`. While `cap` is the amount of storage
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
4850 Second, I included macros that might help branch placement and prediction:
4865 `__builtin_expect((e), 0)`, respectively, on GCC and Clang for better branch
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
5107 [112]: https://git.yzena.com/Yzena/Yc/src/branch/master/include/yc/vector.h
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-…