Installation

The TinyCOBOL compiler can be installed by compiling the source code or by using a prepackaged binary installation such as RPM on Redhat Linux.

An RPM binary installation can work for Linux, but only if the RPM is built specifically for the system that TinyCOBOL is being installed onto. An RPM installation can be challenging, if not impractical, because of software version dependencies.

People experienced with software installation on Linux and BSD recommend installing TinyCOBOL by compiling the source code. Compiling is the simpler and more reliable installation method.

Building TinyCOBOL

Building TinyCOBOL by compiling the source can be a challenging task. The main challenge is putting the Berkeley DB files in the right directories. The TinyCOBOL configure script checks for the Berkeley DB libraries, libdb*.*, in the /usr/local directory. If they are located somewhere else on your system, you will modify, either to the configure script, the location of libdb*.*, or both, as described later in this section.

The configure script will also verify that your system's Berkeley DB is compatible with Berkeley DB version 1.85.4. If your system's Berkeley DB is not compatible, you will must either install a compatible version or reinstall your current version with a version 1.85 compatibility flag. The configure script will also check for a usable Berkeley DB header file. The header file must be in either /usr/include or /usr/include/db*, where * is “1”, “2”, “3”, or “4”.

BSD presents another small challenge. The configure and make scripts are designed to use the dynamic linker, dl, which is in libdl.so. BSD does not have dl or libdl.so. Fortunately, BSD does not need dl, because it uses a different dynamic linker. A few minor modifications are needed in the configure, Makefile, and post installation test scripts to work around this challenge. The modifications are described later in this section.

Compiler requirements

Most of the requirements for compiling TinyCOBOL are included in the installation notes that come with the TinyCOBOL source code package. This section will cover some of the basics, so people who are less experienced with Linux and BSD can do a compiled installation.

You will need:

• The TinyCOBOL v 0.61.x source code package. This can be downloaded from the TinyCOBOL.org homepage. You can use either tinycobol-0.61.tar.gz or
tinycobol-0.61.src.rpm. This manual will only address tinycobol-0.61.tar.gz.

• flex the lexical analyzer must be installed on the target system. Another lexical analyzer can be substituted if you know what you are doing. This manual will only address flex. Verify that flex is installed by executing:

flex --version

• A special version of yacc version 1.9.3, the compiler compiler, must be installed. This is named yacc193 to avoid confusion with other yacc programs. This manual will only address yacc193. Other versions of yacc won't work with TinyCOBOL because they aren't robust enough for COBOL's syntax. bison may also work, but the TinyCOBOL developers found that yacc is more stable. yacc193 should be downloaded from the TinyCOBOL home page because the home page version is the same version used by the TinyCOBOL compiler developers.

• Berkeley DB is needed for reading and writing indexed files. The TinyCOBOL compiler requires the Berkeley DB C header file named db.h or db_185.h. The TinyCOBOL installation process will verify that the appropriate header is on your system.

• A C language compiler. While a number of C compilers might work, GNU C is the default and is recommended. This manual will only address GNU C.. As of this writing, GNU C versions 3.2.x are highly recommended because the compler developers use these versions. More recent versions such as 3.3.x may have some compatibility problems due to changing C standards.

• Miscellaneous utilities that should come with your O/S distribution.

• BSD users will need gmake. Where this documentation refers to make, BSD users should substitute gmake. BSD has a make utility, but it is different from the Linux make. BSD make and Linux make do not work the same way and are not compatible.

• The program lockserver is needed by TinyCOBOL programs that use record locking. lockserver is a server that must be started before a TinyCOBOL program can do record locking. Your system probably does not have lockserver installed on it. If you know your system will never use record locking, lockserver installation is not necessary. lockserver v 1.0 does not seem to work with FreeBSD. Installing lockserver on FreeBSD may make the compiler unusable.

Installing flex

If flex isn't already installed, locate and install an appropriate flex for your system. The installation of flex is outside of the scope of this user manual.

Installing yacc193

yacc193 is usually easy to install.

After downloading yacc-1.9.3-1.tar.gz from the TinyCOBOL.org Downloads page, from a command line cd into its directory and execute:

tar -xvf yacc-1.9.3-1.tar

This will unpack and unarchive the TinyCOBOL yacc193 source files and build files.

cd into the yacc-1.9.3 directory.

Read the installation instructions in the INSTALL.txt file, then read the following before installing.

You must have write permission to the system executables directory to install. If your user id doesn't have write permissions, su to root to install.

make install will put the yacc193 man files into directory /usr/man/man1. Verify that your system has a /usr/man/man1 directory. If your system does not have have directory /usr/man/man1, find your system's man1 directory. It will be full of files with “.gz” extensions and you will see man2 through man9 directories beside man1 in its parent directory. Then edit the yacc193 Makefile, replacing /usr/man/man1 with your system's man1 directory.

make install will put the yacc193 documentation files into /usr/doc/yacc-1.9.3-1 by default. Verify that your system has a /usr/doc directory. If your system does not have directory /usr/doc, either create it or modify the yacc193 Makefile replacing /usr/doc with your system's correct document directory.

Run make from the yacc-1.9.3 directory to build the object code. If using BSD, remember to use gmake instead of make.

Run make install from the yacc-1.9.3 directory to link the object code and install yacc193 and its documentation.

make install will put program yacc193 into directory /usr/local/bin. Verify that
/usr/local/bin is in your PATH environment variable. If it isn't, add /usr/local/bin to your PATH variable.

Berkeley DB

TinyCOBOL uses Berkeley DB to handle indexed files. Berkeley DB must be installed on your system before installing TinyCOBOL. Either Berkeley DB versions 1.85.4 or 1.86 must be installed, or version 2.1 or newer built with version 1.85 compatability must be installed.

Setting up Berkeley DB is often the most difficult part of the installation process. Less experienced Linux and BSD users should leave their Berkeley DB untouched if possible. Installing a version of Berkeley DB which is different from your current version can mess up your system!

As of version 1.86, Berkeley DB uses a database format that is incompatible with earlier versions. When building version 2.1 or newer, the use of

../dist/config --enable-compat185

will build Berkeley DB with an API for version 1.85. If you upgrade from 1.85 to a newer version, you will have to upgrade the database format even if you are using the 1.85 API.

If you install version 1.85.4, make sure you install the patches to the source code before compiling. Without the patch, the source may not compile correctly.

The TinyCOBOL INSTALL file has some relevant developer's notes on installing TinyCOBOL with Berkeley DB. You may need to find where the Berkeley DB library, libdb.so is located on your system. Berkeley DB is usually in /usr/lib, but could be installed elsewhere, such as /usr/local/lib. The TinyCOBOL installer will search for libdb.so. You may need to create a copy or a hard link to your system's Berkeley DB. For example, if your Berkeley DB is version 4.1 and it is installed as /usr/local/lib/libdb41.so, you would us ln -n to create a hard link /usr/lib/libdb.so that points to /usr/local/lib/libdb41.so and, similarly, to create a hard link /usr/lib/libdb.a that points to
/usr/local/lib/libdb41.a.

The TinyCOBOL installer searches for Berkeley DB in /usr/lib by default. If your Berkeley DB is installed in a different directory, you will either have to create hard links from /usr/lib to your Berkeley DB library, or you will have to copy your libdb* files to the /usr/lib directory, or you will have to modify the TinyCOBOL installer so it uses your Berkeley DB library directory.

The TinyCOBOL installer searches for the Berkekely DB header files (db.h or db_185.h) in
/usr/include or /usr/include/db*, where * is “1”, “2”, “3” or “4”. If your system's Berkeley DB header files are not in one of these directories, you must apply a fix similar to the fix for the library files. If /usr/include/db* is not present, you may want to create it before linking to your installation's db.h and db_185.h files.

Unless you are building a specialized application for distribution, you should be able to use your default Berkeley DB installation.

Berkeley DB installation is outside of the scope of this user manual. Sleepycat Software distributes Berkeley DB and has the necessary installation notes. IBiblio.org has older versions of Berkeley DB.

Installing gcc

If gcc isn't already installed, locate and install gcc for your system. gcc installation is outside of the scope of this user manual.

Building TinyCOBOL from Source Code

Download tinycobol-0.61.tar.gz from the TinyCOBOL.org Downloads page. cd into the directory containing tinycobol-0.61 and execute:

gunzip tinycobol-0.61.tar.gz

tar -xvf tinycobol-0.61.tar

This will unpack and unarchive the TinyCOBOL source files and build files.

cd to the tinycobol-0.61 directory.

Read the README file and the installation instructions in the INSTALL file.

The configure script will set up some parameters for building TinyCOBOL. The configure script will examine your system to set up options for the make program. configure uses the bison compiler compiler by default, but this manual uses the yacc193 compiler compiler , so use the command line option --with-yacc=yacc193.

Depending on how your system's Berkeley DB is set up, you might also need to use the option that specifies your version of Berkeley DB, the --with-libdb=[your Berkeley DB version number]. If your systemlibrary directory contains libdb.so and libdb.a, this option is not needed. Otherwise, with libdb1.* use --with-libdb=1, with libdb2.* use --with-libdb=2, with libdb3.* use --with-libdb=3, and with libdb-4.* use --with-libdb=4. Check the INSTALL file and the configure script for more information.

Other configuration options are available. The INSTALL file and the configure script provide more information.

The configure script will set up the system to use the libdl.so library by default. BSD doesn't usually have or need libdl.so, so the following three changes are needed in the configure script in BSD only:

define_with_dl must be assigned a value of "no" or "".

2. Change htg_ld_args_dl=”-ldl” to htg_ld_args_dl=“” Change this in both places in the file.

Remove all other references to -ldl in the main Makefile and the Makefiles in the subdirectories.

Review the options in configure to determine what options you will need. A common option is --enable-lockserv. Create the configuration options by running the appropriate command:

./configure --with-yacc=yacc193 [your options]

or

./configure --with-yacc=yacc193 --with-libdb=# [your options]

Make sure the INSTMAN1 variable in the tinycobol-0.61/info/Makefile file points to your system's man directory. If necessary, edit the tinycobol-0.61/info/Makefile file and change the INSTMAN1 variable to point to the appropriate man directory.

You must have write permission to the system executables directory to install. If your user id doesn't have write permissions, su to root to install and then execute the two commands:

make

make install

If using BSD, remember to use gmake instead of make.

Reboot if necessary and verify the install by running the command:

htcobol -V

Post Installation Tasks

In BSD, the /usr/local/share/htcobol/htcobolrc file will need a minor modification. Two variables refer to the dynamic loader, dl. Because BSD does not normally have dl, all references to dl should be removed. Change

LD_EXTRA_LIBS: -ldl
LD_DCALL_LIBS: -ldl

to

LD_EXTRA_LIBS:
LD_DCALL_LIBS:

The htcobol program uses a variable, LD_PATH, in the htcobolrc file to point to the linker libraries. The installer assigns a value which is useful for building and testing the compiler. Change this variable to point to your library directories. Normally, you will change the variable as follows:

LD_PATH: -L. -L/usr/lib -L/usr/local/lib

If your installation will use statically linked libraries, you must install the static libraries. To install the statically linked libraries, cd to the TinyCOBOL ./lib directory and run:

make devel

make install-static

If you are using lockserver, build it now if you have not already done so. Please be aware that lockserver may not work with FreeBSD.

Verifying the Compiler Build

After building TinyCOBOL, test it to ensure that it works correctly. Run the test suites included in the TinyCOBOL tar file. Running the test suites is relatively easy.

cd to the test_suite directory. If you are using BSD, the main testing script cobol_test.pl, must be modified because it uses dl, which is not normally installed on BSD. A variable must be modified to prevent the test script from crashing. Remove -ldl from the line:

$LIBS=$g_libraries . " -L../../lib -lhtcobol " . $LIBDBNAME . " -ldl" . " -lm";

like so:

$LIBS=$g_libraries . " -L../../lib -lhtcobol " . $LIBDBNAME . " -lm";

Execute make. You should get almost all PASSed messages in the TEST###.log file. A few COBOL verbs are not fully implemented at this time, so a handful of tests will fail. The FAILs will mostly be SELECT and INSPECT statements. Those are expected in this version of Tiny COBOL.

Dynamic linking can be a problems, so compile and run the dyntest program in test.code/t33 to verify dynamic linking. Expect some successful tests as well as failure test.

Installation Using an RPM Binary

RPM installation is not recommended unless you know that the RPM was built specifically for your system. Even if the RPM was built for your O/S distribution, RPM still may not work. If you use an RPM installation, RPM is simple so this manual will not discuss how to us it. If you attempt an RPM install and RPM can't install because of numerous library dependencies, you probably should build TinyCOBOL from the source code.

Uninstalling

Uninstalling a TinyCOBOL RPM is trivial and will not be addressed in this manual.

To uninstall from a compiled version, cd to the tinycobol-0.61 directory and execute the two commands:

make cleanall

make distclean

2004-01-28T17:18:09