##============================================================================= ## ## This file is part of BibTool. ## It is distributed under the GNU General Public License. ## See the file COPYING for details. ## ## (c) 1996-2004 Gerd Neugebauer ## ## Net: gene@gerd-neugebauer.de ## ##***************************************************************************** This file contains instructions and hints for the compilation of BibTool. Table of Contents 0. Introduction 1. Prerequisites 2. Generic Installation Procedure 3. Installation on UNIX 4. Installation on MSDOS-like Computers 5. Installation on Amiga 6. Installation without make 7. Using the kpathsea library 8. Problems and Porting 9. The C Interface 10. The Tcl/Tk Interface 0. Introduction =============== BibTool is known to work on the following operating systems/C compilers: (At least an earlier version has been compiled successfully on them.) Linux gcc Sun4/SunOS4.1.* cc, gcc SparcStation/Solaris2.4 gcc SparcStation/Solaris2.5 gcc Sun3/SunOS4.1.1 cc HP 9000/4??/HP UX ?? cc Atari ST/TOS 1.2 Laser C, Pure C I have been informed that BibTool has been compiled on the following machines/operating systems (and maybe some more that I have forgotten to add to this list;-): AIX 3.2.5 gcc AIX 4.1.4 Amiga SAS/C DEC Alpha/OSF/1 HP 9000/778/HP-UX 10.20 gcc 2.7.2.3 MIPS/Ultrix4.4 gcc 2.4.5 MIPS/RISCos 4.52 gcc MSDOS,OS/2,Win32,WinNT emx, dj, Watcom C, MSC MS-Windows 4.0, Sp 6 Cygwin IBM PC 486DX2-66, OS/2 Merlin 4.0 FixPack #5. EMX v.0.9c+GCC+dmake 4.0 NeXT SGI Indigo2/IRIX 6.2 cc If you compile BibTool on other systems drop me a mail. I'm interested to support a broad variety of systems/compilers. Gerd Neugebauer Mainzer Str. 8 56321 Rhens (Germany) Net: gene@gerd-neugebauer.de You can also send me a mail if you encounter problems in compiling BibTool, or crashes, or shows unexpected (contradicting the documentation) behavior of the final program. Please enclose a precise description what went wrong. Include the version numbers of BibTool, your computer, your operating system, and your C compiler. If you encounter unexpected behavior of BibTool enclose your resource file(s) and a _SMALL_ BibTeX file demonstrating the problem. Describe how you have invoked BibTool (arguments) and justify why you think that there is a problem. I know that this sounds like work. But otherwise I will not be able to give you proper advice or find a bug in the sources. 1. Prerequisites ================ To install BibTool you need: - A C compiler. ANSI-C is not required but highly recommended. Several library functions are expected. You will see if your linker complains. - A running version of make is recommended. 2. Generic Installation Procedure ================================= See if there is a special section for your computer/C compiler and follow the instructions given there. Most probably you will be directed back into this section after some initial actions. See Section 7 and see if it applies to your setting. To install BibTool you can try to apply the following instructions: A Copy one of the prepared makefiles to makefile and adjust it according to your C compiler. The following makefiles should be present in the distribution: makefile.unx This is the generic makefile. Especially it is for all UN*X systems and may provide a basis for compilation on systems not explicitly mentioned here. makefile.dos This is the makefile for MSDOS based machines. makefile.ata This is the makefile for Atari ST/TT computers. makefile.ami This is the makefile for Amiga computers (with SAS/C). Edit the makefile and adjust the settings in the configuration section according to your needs. Maybe you have to adapt the name and options for your C compiler. (Most of the time I prefer the GNU C compiler) Maybe you want to change the location for the installation target, even though reasonable defaults are provided. B Look into the file include/bibtool/config.h to see if it fits your operating system and C compiler. Adjust things as required. Most probably you do not have to change anything in this file. This file is mainly for those with an old C compiler (non-ANSI). C If you want to configure some of the internals of BibTool you can have a look into include/bibtool/bibtool.h. It contains the internal configuration options which used to be in config.h prior to release 2.39. Most probably there is no need to change the defaults given there. One exception is the support for another language by specifying additional words to be ignored. (Maybe I could include them into the distribution; thus drop me a mail if you do so) D If you have a working makedepend command run make depend Otherwise just skip this step. It is only helpful if you compile BibTool more than once. This might cause problems if the makedepend command does not fit the C compiler used (e.g. proprietary makedpend together with gcc). This results in unknown files to show up. In this case also skip this step and revert to the original makefile. E Afterwards run make Most probably this should produce the executable bibtool (or bibtool.exe, or bibtool.ttp, or ...) in the current directory. F If you have tried the command bibtool in the current directory you can install it with make install to install the executable and the libraries and make install.man to install the UN*X man pages. This is only useful if you can make use of them, i.e. on a UN*X-like system. G To get rid of all intermediate files run make clean H To prepare the documentation contained in the subdirectory Doc go into the Doc subdirectory and run latex bibtool latex bibtool bibtex bibtool makeidx bibtool latex bibtool latex bibtool The makeidx program may be named differently on your system or missing at all. In this case you can omit this step and do without the index. On UN*X you can try make doc which tries to perform the steps given above. The documentation is written in a way that either LaTeX or LaTeX2.09 can be used to compile it. I had a bug report about a real ancient LaTeX2.09 and I am not sure I have completely fixed it. Thus the best is to use an up-to-date LaTeX. There might be problems when files produced by LaTeX2.09 should be read by LaTeX2e and vice versa. In this case you can try to remove the intermediate files bibtool.toc bibtool.ind and follow the instruction for making the documentation from the beginning. 3. Installation on UNIX ======================= Some special preparations have been made for UNIX systems. autoconf scripts are provided which try to find out the characteristics of the system automatically. General instructions: A Run the configure script with the command: ./configure The following options are useful for configure: --with-kpathsea try to find the kpathsea library either in the current directory or in the previous directory. Thus you can place the BibTool directory in the same directory where the directory kpathsea resides or you can put the kpathsea directory in in the BibTool directory. (default) (See also section 7) --without-kpathsea disable the search for the kpathsea library. --prefix=PREFIX install architecture-independent files in PREFIX [/usr/local] --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX [same as prefix] --bindir=DIR the bibtool executable is stored in DIR [EPREFIX/bin] --libdir=DIR the BibTool directory containing certain resource files are stored in DIR [EPREFIX/lib] --mandir=DIR the manual pages bibtool.1 is stored in DIR [PREFIX/man] B Continue with the item C in section 2. 4. Installation on MSDOS-like Computers ======================================= This section some hints on the compilation of BibTool on MSDOS computers. These adaptions are mainly due to the efforts of Josef Spangler (JS@rphnw3.ngate.uni-regensburg.de). All credits go to him. Any remaining problems should be blamed on my ignorance. General instructions: A Copy makefile.dos to makefile and adjust it according to your C compiler. B Edit include/bibtool/config.h and include/bibtool/bibtool.h to adjust it to your needs. Normally you should be interested only in the support of emTeX at the end of include/bibtool/bibtool.h. C Copy MSDOS\link.* to the source directory. D Depending on the C compiler do the following: - dj (GNU C port) make dj - emx (GNU C port) make emx Maybe you have to set the environment variable EMX to point to the installed EMX directory. - Watcom C 386 (32 Bit Compiler for Dos, OS/2 2.x, Win32 and WinNT) make wat - Microsoft C 6.00A (16 Bit Dos and OS/2 1.x) make msc - Borland C++ 3.1 (16 Bit Dos) Go and get another compiler. Or, even better do the port and send me the diffs :-) E If you have tried the command bibtool in the current directory you can install it with make install F Make the documentation according to step H in section 2. 5. Installation on Amiga ======================== This section contains some hints on the compilation of BibTool on Amiga computers. These adaptions are mainly due to the efforts of Andreas Scherer (SCHERER@genesis.informatik.rwth-aachen.de). All credits go to him. Any remaining problems should be blamed on my ignorance. This section describes the installation procedure if you are using the SAS/C compiler on Amiga. General instructions: A Copy makefile.ami to SMakefile and adjust it accordingly. B Edit the file include/bibtool/config.h and include/bibtool/bibtool.h and adjust it to your needs. There should not be much for you to change. C make E If you have tried the command bibtool in the current directory you can install it with make install D Make the documentation according to step H in section 2. 6. Installation without make ============================ A Adjust the settings in the files include/bibtool/config.h and include/bibtool/bibtool.h to fit your C compiler and operating system. B Compile all .c files in the base directory. The macros REGEX and maybe MSDOS should be defined. The subdirectory regex-0.12 should be included in the include search path. A typical compile command looks like cc main.c -c -o main.o -DREGEX -DMSDOS -Iregex-0.12 -I. C Compile regex.c in the regex-0.12 subdirectory and move the object file into the base directory (The one containing this file). D Link together all object files to get the executable bibtool. (maybe include the kpathsea library; see section 6) E Run LaTeX on bibtool.tex in the Doc subdirectory to produce the documentation. (see step H in section 2 for details) 7. Using the kpathsea library ============================= The kpathsea library provides a very flexible way to specify the search path for files. This library is already used by the web2c distribution of Karl Berry and the teTeX distribution. To achieve compatibility with those TeX systems you can try to make BibTool use the same library. The kpathsea library is currently NOT CONTAINED in the distribution of BibTool since this is an experimental feature. You can get kpathsea from the same location where you got BibTool. Fetch the file kpse2-6.tar.gz or kpse2-6.zip. Unpack this file. Enter the directory kpse2-6 and use the commands `./configure' and `make' to create the library. This works at least on Unix platforms. For porting to other platforms I would like to get some feedback. ATTENTION: The kpathsea library has to exists before BibTool is made! If you are using configure then the option --with-kpathsea enables the inclusion of the kpathsea routines if the library is found. To use the library you can just provide three definitions in the makefile. See the section about kpathsea in makefile for explanations. Alternatively you have to provide the appropriate options to the C compiler yourself. Note: the searching for BibTeX files with the kpathsea library is different from the BibTool built-in searching. Some resources are no longer taken into account when this library is used. Note: kpathsea is only used to search for BibTeX files. All other files are still searched with the traditional BibTool searching mechanism. This might change soon. 8. Problems and Porting ======================= Well, if the procedures described above don't work I have some hints. These hints may also be useful if you plan to port BibTool to other operating systems or C compilers. First of all a small list of assumptions that I use. - On ANSI systems there should be no problem at all. There is some support for non-ANSI systems. This support can be improved. (I don't know if it's worthwhile to do so). - BibTool has been developed on UN*X (SunOS) and UN*X-like systems (Atari). Such file/directory naming conventions found their way into the code. Single character delimiters between directories and files can be modified in a resource file. - ASCII encoding is assumed. I role my own type.h instead of using ctypes.h. This has mainly historical reasons. Maybe this code should be rewritten to be adapted at make time. If you port BibTool to a non-ASCII machine the table of characters (allowed[]) in type.h has to be adapted -- at least (please send me the diffs). - Maybe some BSD-isms found their way into the code even if I am not aware of it. 9. The C Interface ================== The C interface to BibTool is described in the document Doc/c_lib.dvi. To create this document run LaTeX and makeindex on the file c_lib.tex in the Doc subdirectory: latex c_lib makeindex c_lib latex c_lib latex c_lib Read this document. I would like some kind of feedback for this attempt. Attention: This documentation is experimental. Some things are likely to be changed soon. 10. The Tcl/Tk Interface ======================== The Tcl/Tk interface is called BibTcl. It is contained in the BibTcl subdirectory. See the file README in this directory for details.