This is a production release that fixes a bug. The bug was that if an array element was used as a parameter, and then a later parameter had the same name as the array whose element was used, bc would grab the element from the new array parameter, not the actual element from before the function call. |
||
---|---|---|
gen | ||
include | ||
locales | ||
manuals | ||
scripts | ||
src | ||
tests | ||
vs | ||
.gitattributes | ||
bcl.pc.in | ||
configure | ||
configure.sh | ||
LICENSE.md | ||
Makefile.in | ||
MEMORY_BUGS.md | ||
NEWS.md | ||
NOTICE.md | ||
README.md |
bc
WARNING: New user registration for https://git.yzena.com/ is disabled because
of spam. If you need to report a bug with bc
, email gavin at this site minus
the git.
part for an account, and I will create one for you. Or you can report
an issue at GitHub.
WARNING: This project has moved to https://git.yzena.com/ for these reasons, though GitHub will remain a mirror.
This is an implementation of the POSIX bc
calculator that implements
GNU bc
extensions, as well as the period (.
) extension for the BSD
flavor of bc
.
For more information, see this bc
's full manual.
This bc
also includes an implementation of dc
in the same binary, accessible
via a symbolic link, which implements all FreeBSD and GNU extensions. (If a
standalone dc
binary is desired, bc
can be copied and renamed to dc
.) The
!
command is omitted; I believe this poses security concerns and that such
functionality is unnecessary.
For more information, see the dc
's full manual.
This bc
also provides bc
's math as a library with C bindings, called bcl
.
For more information, see the full manual for bcl
.
License
This bc
is Free and Open Source Software (FOSS). It is offered under the BSD
2-clause License. Full license text may be found in the LICENSE.md
file.
Prerequisites
This bc
only requires either:
- Windows 10 or later, or
- A C99-compatible compiler and a (mostly) POSIX 2008-compatible system with the XSI (X/Open System Interfaces) option group.
Since POSIX 2008 with XSI requires the existence of a C99 compiler as c99
, any
POSIX and XSI-compatible system will have everything needed.
POSIX-compatible systems that are known to work:
- Linux
- FreeBSD
- OpenBSD
- NetBSD
- Mac OSX
- Solaris* (as long as the Solaris version supports POSIX 2008)
- AIX
- HP-UX* (except for history)
In addition, there is compatibility code to make this bc
work on Windows.
Please submit bug reports if this bc
does not build out of the box on any
system.
Build
This bc
should build unmodified on any POSIX-compliant system or on Windows
starting with Windows 10 (though earlier versions may work).
For more complex build requirements than the ones below, see the build manual.
Windows
There is no guarantee that this bc
will work on any version of Windows earlier
than Windows 10 (I cannot test on earlier versions), but it is guaranteed to
work on Windows 10 at least.
Also, if building with MSBuild, the MSBuild bundled with Visual Studio is required.
Note: Unlike the POSIX-compatible platforms, only one build configuration is supported on Windows: extra math and history enabled, NLS (locale support) disabled, with both calculators built.
bc
To build bc
, you can open the vs/bc.sln
file in Visual Studio, select the
configuration, and build.
You can also build using MSBuild with the following from the root directory:
msbuild -property:Configuration=<config> vs/bc.sln
where <config>
is either one of Debug
or Release
.
On Windows, the calculators are built as vs/bin/<platform>/<config>/bc.exe
and
vs/bin/<Platform>/<Config>/dc.exe
, where <platform>
can be either Win32
or
x64
, and <config>
can be Debug
or Release
.
Note: On Windows, dc.exe
is just copied from bc.exe
; it is not linked.
Patches are welcome for a way to do that.
bcl
(Library)
To build the library, you can open the vs/bcl.sln
file in Visual Studio,
select the configuration, and build.
You can also build using MSBuild with the following from the root directory:
msbuild -property:Configuration=<config> vs/bcl.sln
where <config>
is either one of Debug
, ReleaseMD
, or ReleaseMT
.
On Windows, the library is built as vs/lib/<platform>/<config>/bcl.lib
, where
<platform>
can be either Win32
or x64
, and <config>
can be Debug
,
ReleaseMD
, or ReleaseMT
.
POSIX-Compatible Systems
On POSIX-compatible systems, bc
is built as bin/bc
and dc
is built as
bin/dc
by default.
Default
For the default build with optimization, use the following commands in the root directory:
./configure.sh -O3
make
One Calculator
To only build bc
, use the following commands:
./configure.sh --disable-dc
make
To only build dc
, use the following commands:
./configure.sh --disable-bc
make
Debug
For debug builds, use the following commands in the root directory:
./configure.sh -g
make
Install
To install, use the following command:
make install
By default, bc
and dc
will be installed in /usr/local
. For installing in
other locations, use the PREFIX
environment variable when running
configure.sh
or pass the --prefix=<prefix>
option to configure.sh
. See the
build manual, or run ./configure.sh --help
, for more details.
Library
To build the math library, pass the -a
or --library
options to
configure.sh
:
./configure.sh -a
When building the library, the executables are not built. For more information, see the build manual.
The library API can be found in manuals/bcl.3.md
or man bcl
once the
library is installed.
Package and Distro Maintainers
This section is for package and distro maintainers.
Out-of-Source Builds
Out-of-source builds are supported; just call configure.sh
from the directory
where the actual build will happen.
For example, if the source is in bc
, the build should happen in build
, then
call configure.sh
and make
like so:
../bc/configure.sh
make
WARNING: The path to configure.sh
from the build directory must not have
spaces because make
does not support target names with spaces.
Recommended Compiler
When I ran benchmarks with my bc
compiled under clang
, it performed much
better than when compiled under gcc
. I recommend compiling this bc
with
clang
.
I also recommend building this bc
with C11 if you can because bc
will detect
a C11 compiler and add _Noreturn
to any relevant function(s).
Recommended Optimizations
I wrote this bc
with Separation of Concerns, which means that there are many
small functions that could be inlined. However, they are often called across
file boundaries, and the default optimizer can only look at the current file,
which means that they are not inlined.
Thus, because of the way this bc
is built, it will automatically be slower
than other bc
implementations when running scripts with no math. (My bc
's
math is much faster, so any non-trivial script should run faster in my bc
.)
Some, or all, of the difference can be made up with the right optimizations. The optimizations I recommend are:
-O3
-flto
(link-time optimization)
in that order.
Link-time optimization, in particular, speeds up the bc
a lot. This is because
when link-time optimization is turned on, the optimizer can look across files
and inline much more heavily.
However, I recommend NOT using -march=native
. Doing so will reduce this
bc
's performance, at least when building with link-time optimization. See the
benchmarks for more details.
Stripping Binaries
By default, non-debug binaries are stripped, but stripping can be disabled with
the -T
option to configure.sh
.
Using This bc
as an Alternative
If this bc
is packaged as an alternative to an already existing bc
package,
it is possible to rename it in the build to prevent name collision. To prepend
to the name, just run the following:
EXECPREFIX=<some_prefix> ./configure.sh
To append to the name, just run the following:
EXECSUFFIX=<some_suffix> ./configure.sh
If a package maintainer wishes to add both a prefix and a suffix, that is allowed.
Note: The suggested name (and package name) when bc
is not available is
bc-gh
.
Karatsuba Number
Package and distro maintainers have one tool at their disposal to build this
bc
in the optimal configuration: scripts/karatsuba.py
.
This script is not a compile-time or runtime prerequisite; it is for package and distro maintainers to run once when a package is being created. It finds the optimal Karatsuba number (see the algorithms manual for more information) for the machine that it is running on.
The easiest way to run this script is with make karatsuba
.
If desired, maintainers can also skip running this script because there is a sane default for the Karatsuba number.
Status
This bc
is robust.
It is well-tested, fuzzed, and fully standards-compliant (though not certified)
with POSIX bc
. The math has been tested with 40+ million random problems, so
it is as correct as I can make it.
This bc
can be used as a drop-in replacement for any existing bc
. This bc
is also compatible with MinGW toolchains.
In addition, this bc
is considered complete; i.e., there will be no more
releases with additional features. However, it is actively maintained, so if
any bugs are found, they will be fixed in new releases. Also, additional
translations will also be added as they are provided.
Development
If I (Gavin D. Howard) get hit by a bus and future programmers need to handle work themselves, the best place to start is the Development manual.
Vim Syntax
I have developed (using other people's code to start) vim
syntax files
for this bc
and dc
, including the extensions.
bc
Libs
I have gathered some excellent bc
and dc
libraries. These libraries
may prove useful to any serious users.
Comparison to GNU bc
This bc
compares favorably to GNU bc
.
- This
bc
builds natively on Windows. - It has more extensions, which make this
bc
more useful for scripting. (See Extensions.) - This
bc
is a bit more POSIX compliant. - It has a much less buggy parser. The GNU
bc
will give parse errors for what is actually validbc
code, or should be. For example, putting anelse
on a new line after a brace can cause GNUbc
to give a parse error. - This
bc
has fewer crashes. - GNU
bc
calculates the wrong number of significant digits forlength(x)
. - GNU
bc
will sometimes print numbers incorrectly. For example, when running it on the filetests/bc/power.txt
in this repo, GNUbc
gets all the right answers, but it fails to wrap the numbers at the proper place when outputting to a file. - This
bc
is faster. (See Performance.)
Performance
Because this bc
packs more than 1
decimal digit per hardware integer, this
bc
is faster than GNU bc
and can be much faster. Full benchmarks can be
found at manuals/benchmarks.md.
There is one instance where this bc
is slower: if scripts are light on math.
This is because this bc
's intepreter is slightly slower than GNU bc
, but
that is because it is more robust. See the benchmarks.
Extensions
Below is a non-comprehensive list of extensions that this bc
and dc
have
that all others do not.
- An extended math library. (See here for more information.)
- A command-line prompt.
- Turning on and off digit clamping. (Digit clamping is about how to treat
"invalid" digits for a particular base. GNU
bc
uses it, and the BSDbc
does not. Mine does both.) - A pseudo-random number generator. This includes the ability to set the seed and get reproducible streams of random numbers.
- The ability to use stacks for the globals
scale
,ibase
, andobase
instead of needing to restore them in every function. - The ability to not use non-standard keywords. For example,
abs
is a keyword (a built-in function), but if some script actually defines a function called that, it's possible to tell mybc
to not treat it as a keyword, which will make the script parses correctly. - The ability to turn on and off printing leading zeroes on numbers greater than
-1
and less than1
. - Outputting in scientific and engineering notation.
- Accepting input in scientific and engineering notation.
- Passing strings and arrays to the
length()
built-in function. (Indc
, theY
command will do this for arrays, and theZ
command will do this for both numbers and strings.) - The
abs()
built-in function. (This is theb
command indc
.) - The
is_number()
andis_string()
built-in functions. (These tell whether a variable is holding a string or a number, for runtime type checking. The commands areu
andt
indc
.) - For
bc
only, thedivmod()
built-in function for computing a quotient and remainder at the same time. - For
bc
only, theasciify()
built-in function for converting an array to a string. - The
$
truncation operator. (It's the same inbc
anddc
.) - The
@
"set scale" operator. (It's the same inbc
anddc
.) - The decimal shift operators. (
<<
and>>
inbc
,H
andh
indc
.) - Built-in functions or commands to get the max of
scale
,ibase
, andobase
. - The ability to put strings into variables in
bc
. (This always existed indc
.) - The
'
command indc
for the depth of the execution stack. - The
y
command indc
for the depth of register stacks. - Built-in functions or commands to get the value of certain environment variables that might affect execution.
- The
stream
keyword to do the same thing as theP
command indc
. - Defined order of evaluation.
- Defined exit statuses.
- All environment variables other than
POSIXLY_CORRECT
,BC_ENV_ARGS
, andBC_LINE_LENGTH
. - The ability for users to define their own defaults for various options during build. (See here for more information.)
Algorithms
To see what algorithms this bc
uses, see the algorithms manual.
Locales
Currently, there is no locale support on Windows.
Additionally, this bc
only has support for English (and US English), French,
German, Portuguese, Dutch, Polish, Russian, Japanese, and Chinese locales.
Patches are welcome for translations; use the existing *.msg
files in
locales/
as a starting point.
In addition, patches for improvements are welcome; the last two messages in Portuguese were made with Google Translate, and the Dutch, Polish, Russian, Japanese, and Chinese locales were all generated with DeepL.
The message files provided assume that locales apply to all regions where a
language is used, but this might not be true for, e.g., fr_CA
and fr_CH
.
Any corrections or a confirmation that the current texts are acceptable for
those regions would be appreciated, too.
Other Projects
Other projects based on this bc are:
-
busybox
bc
. The busybox maintainers have made their own changes, so any bugs in the busyboxbc
should be reported to them. -
toybox
bc
. The maintainer has also made his own changes, so bugs in the toyboxbc
should be reported there. -
FreeBSD
bc
. While thebc
in FreeBSD is kept up-to-date, it is better to report bugs there, as well as submit patches, and the maintainers of the package will contact me if necessary.
Language
This bc
is written in pure ISO C99, using POSIX 2008 APIs with custom Windows
compatibility code.
Commit Messages
This bc
uses the commit message guidelines laid out in this blog post.
Semantic Versioning
This bc
uses semantic versioning.
Contents
Items labeled with (maintainer use only)
are not included in release source
tarballs.
Files:
.gitignore The git ignore file (maintainer use only).
.gitattributes The git attributes file (maintainer use only).
bcl.pc.in A template pkg-config file for bcl.
configure A symlink to configure.sh to make packaging easier.
configure.sh The configure script.
LICENSE.md A Markdown form of the BSD 2-clause License.
Makefile.in The Makefile template.
NEWS.md The changelog.
NOTICE.md List of contributors and copyright owners.
Folders:
benchmarks A folder of benchmarks for various aspects of bc performance.
gen The bc math library, help texts, and code to generate C source.
include All header files.
locales Locale files, in .msg format. Patches welcome for translations.
manuals Manuals for both programs.
src All source code.
scripts A bunch of shell scripts to help with development and building.
tests All tests.
vs Files needed for the build on Windows.