HOWTO.INSTALL

# Installing a pre-compiled calc from an RPM

If your platform supports RPMs, you may want to go to:

    https://github.com/lcn2/calc/releases

and see if there is a pre-compiled version of calc that you may install.

Open up the 'Assets' tag below a given release and download these RPMs:

    * calc*.rpm

	- all that is needed if you just want to use calc

If your platform supports rpm and matches one of the "calc*.rpm" files, you
may just install that "calc*.rpm".  For exammple on an x86_64 system:

    dnf install calc-x.y.z.cv-ww.x86_64.rpm

where "calc-x.y.z.cv-ww.x86_64.rpm" is the name of the calc RPM.

In addition, if your platform supports rpm and matches one of the
"calc*.rpm" files, you may also install the calc *.h header and *.a lib
files for use in other programs:

    * calc-devel-*.rpm

	- calc *.h header and *.a lib files for use in other programs

Alternately to the above github link, you might try looking at the RPMs under:

    http://www.isthe.com/chongo/src/calc/



# Building calc from a source tree



## Step 0: Obtain the calc source tree

Go to the site:

    https://github.com/lcn2/calc/releases

Look for release with a file of the form:

    calc-x.y.z.v.tar.bz2

A release marked with a green "(Latest)" is a production release
that as undergone a fair amount of testing.

A release marked with an orange "(Pre-release)" is likly to be
more stable than the top of the master branch, as they do undergo
thru a reasonable level of regression testing, just not to
the level of a  "(Latest)" production release.

Use the followig command to uncompress the bzip2 compressed tarball:

    bunzip2 -c calc-*.tar.bz2 | tar -xvf -

NOTE: An alternate location for calc bzip2 compressed tarballs is:

    http://www.isthe.com/chongo/src/calc/



### Obtaining the experimental top of the master branch calc source

You may also fetch the top of the master branch of the GitHub repo
if you wish to see what the latest source code looks like:

    git clone https://github.com/lcn2/calc.git

IMPORTANT:

The latest source code may be "experimental in nature".   You may be
better off using a released bzip2 compressed tarball instead.
Released bzip2 compressed tarballs tend to be more well tested
than the top of the master branch.



## Step 1: Makefile considerations


### IMPORTANT: Make support of conditional syntax required:

To compile calc, you must use a make that supports the use of
"Conditional syntax".  As nearly all modern make tools
support "Conditional syntax", thus should not be a problem
for you.  If for some reason your make tool does not support
"Conditional syntax", consider upgraded to a make that does,
such as the Gnu Make tool:

    https://www.gnu.org/software/make/

The Gnu Make is not required per-se, just a modern make tool
that supports "Conditional syntax".


### Review Makefiles

Review Makefile.config and Makefile.target.

If you are curious, review Makefile as well, although
there may be little in the main Makefile that you may
want to change.

Consider modifying Makefile.local by replace values or
appending values found in Makefile.config and Makefile.target.

If you are adding custom functions, review custom/Makefile
and modify custom/Makefile as needed.



### Suggestion: Modify Makefile.local

All Makefiles include Makefile.local just before the
first and default all rule.  So Makefile.local may be
used to modify, replace or append values to Makefile variables.

In most cases, to change the way that calc is made, consider
adding lines to Makefile.local instead of modifying other Makefiles.

A recommended way to adjust it is to add lines to: Makefile.local
using the := syntax to replace values such as:

    DEBUG:= -O0 -g

or by using the += syntax to append to values such as:

    DEBUG+= -ipa

You can, of course, modify other Makefiles.  We only
suggest using Makefile.local to minimize the number
of source files you modify.

And finally, you can always just add arguments to your
make command line instead of modifying a Makefile.  For example:

    make clobber all DEBUG="-O0 -g"


## readline package assumed by default:

By "readline package" we refer to the combination of the
readline library, the history library, and the ncurses library.

By default, calc assumes you have the readline package installed.
The readline package (-lreadline, -lhistory, -lncurses) used by and
linked into calc by default.

If your system (such as macOS) does NOT have those libaraies, then
you have two options:



### Install the readline package:

We recommend that you install the readline package first, then compile calc.

For information on the readline package, see:

    https://tiswww.case.edu/php/chet/readline/rltop.html

MacOS users can use MacPorts or HomeBrew to install readline:

    https://www.macports.org
    https://brew.sh

Or compile from the readline.git repo:

    http://git.savannah.gnu.org/cgit/readline.git/



### Compile calc without readline:

Why do we not recommend this option because using calc with readline
provides a beter user experience.

If you feel you must use calc without the readline package, then you
will need to compile with:

    make clobber all USE_READLINE= READLINE_EXTRAS= READLINE_INCLUDE= READLINE_LIB=

or add to Makefile.local, these lines:

    USE_READLINE=
    READLINE_EXTRAS=
    READLINE_INCLUDE=
    READLINE_LIB=

See the "Suggestion: Modify Makefile.local" section above for
information on the Makefile.local file.


### Windows or a Windows-like environments:

Currently Windows is not a well supported platform for calc.  There are
people within Microsoft who plan to assist us in being able to allow
the standard Microsoft Windows developor environment to compile calc.



### Makefile variables to consider:

You should determine if these Makefile variables are reasonable:

    INCDIR		Where the system include (.h) files are kept.
    BINDIR		Where to install calc binary files.
    LIBDIR		Where to install calc link library (*.a) files.
    CALC_SHAREDIR	Where to install calc help, .cal, startup, and config files.

You may want to change the default installation locations for
these values, which are based on the 4 values listed above:

    HELPDIR            where the help directory is installed
    CALC_INCDIR        where the calc include files are installed
    CUSTOMCALDIR       where custom *.cal files are installed
    CUSTOMHELPDIR      where custom help files are installed
    CUSTOMINCDIR       where custom .h files are installed
    SCRIPTDIR          where calc shell scripts are installed

If you want to install calc files under a top level directory, then set the T value:

    The calc install is performed under ${T}, the calc build is
    performed under /.	The purpose for ${T} is to allow someone
    to install calc somewhere other than into the system area.

    For example, if:

	BINDIR= /usr/bin
	LIBDIR= /usr/lib
	CALC_SHAREDIR= /usr/share/calc

    and if:

	T= /var/tmp/testing

    Then the installation locations will be:

	calc binary files:	/var/tmp/testing/usr/bin
	calc link library:	/var/tmp/testing/usr/lib
	calc help, .cal ...:	/var/tmp/testing/usr/share/calc
	... etc ...		/var/tmp/testing/...

    If ${T} is empty, calc is installed under /, which is the same
    top of tree for which it was built.  If ${T} is non-empty, then
    calc is installed under ${T}, as if one had to chroot under
    ${T} for calc to operate.

Again, consider adding replacement lines or append linbes to
the Makefile.local file.  See "Suggestion Modify Makefile.local
instead of Makefile" above.  For example:

    T:= /var/tmp/testing

See the "Suggestion: Modify Makefile.local" section above for
information on the Makefile.local file.


### platform target section

The file, Makefile.target, contains information about various platforms.
The current list of targets in Makefile.target are:

- Linux target
- Apple macOS / Darwin target
- FreeBSD target
- OpenBSD target
- Cygwin target (as well as Msys2 / Msys OSNAME)
- simple target
- default target (when target is empty)

If you wish to modiy your target platform, consider doing
so via the Makefile.local file.  See "Suggestion Modify Makefile.local
instead of Makefile" above.



## Step 2: compile calc

Remove any previous compile attempts and compile by default:

    make clobber all



### Force calc to build with only static libs:

You may force calc to build with only static libs:

    make clobber calc-static-only BLD_TYPE=calc-static-only



### Force calc to build with only dynamic shared libs:

You may force calc to build with only dynamic libs:

    make clobber calc-dynamic-only BLD_TYPE=calc-dynamic-only



### Reports of compiler warnings (and errors) as welcome

We are interested learning about any compiler warnings (and errors) that you may find.
See the BUGS file if you find any compiler warning or errors.



### Step 3: test calc

You may run the calc regression test suite, after successfully compiling, by:

    make check

For a more quiet check which only prints if something goes wrong, use:

    make chk



### Step 4: install calc

Depending on permissions, you may need to become the super-user:

    sudo -s

before you install:

    make install



### Step n: calc help - getting started

Calc is distributed with an extensive collection of help files that
are accessible from the command line.  The following assume that you
are running calc from the distribution directory or that you have
installed calc.	 In these examples, the "; " is the calc prompt, not
something that you type.

For list of help topics:

    ; help

For overview of calc overview:

    ; help intro
    ; help overview
    ; help command
    ; help define
    ; help statement
    ; help variable
    ; help usage

For list of builtin functions:

    ; help builtin

C programmers should note some unexpected differences with the calc syntax:

    ; help unexpected

Calc is shipped with a standard collection of calc resource files.
For a list of calc standard resource files see:

    ; help resource

We suggest that you might want to read the README.FIRST file and look at
the calc help subsystem.  See also the README.md file.

In general, if you run into problems, read the BUGS file and follow the instructions.

# IMPORTANT: parallel make not supported

We do not support making calc using a parallel make as most parallel
make systems fail to understand the depedency relationships between
a numner of important make rules and thus fail to properly compile calc.



## Copyright (C) 1999-2007,2021,2023  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## Under source code control:	1999/09/27 20:48:44
## File existed as early as:	1999
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/