The Quoteriser, Version 2.10

Source Code

Contents:

  1. Introduction
  2. What you need
  3. Manifest
  4. Compile notes
    1. Compilers other than EMX
    2. Make utilities other than GNU
    3. What might need to be changed
    4. GNU database manager
    5. GNU Rx
  5. Using another regular expression library
  6. A minimal Quoteriser
  7. Systems other than OS/2
  8. Help

Introduction

The author of the Quoteriser supports open source development, so here is the full C source code for the Quoteriser. Customise it, use it to build your own applications, use it as an example to refer to, compile for your favourite operating system, whatever you like, just obey the GNU General Public Licence (or my licence for the xtype library).

This file only documents how to compile the Quoteriser. If the reader wishes to change the source code, he or she will find all the documentation that exists in the source code itself, which the author hopes is reasonably useful.


What you need

Unfortunately, to compile the Quoteriser the reader will need a few packages on top of the Quoteriser source package itself. This is because the Quoteriser uses a few third-party libraries to save its author some work.

The files required by the prospective Quoteriser do-it-yourselfers are:

quot210s.zip
The Quoteriser source code itself; this file is in it, so one presumes the reader already has it.
gnugdbm.zip
The GNU database manager, which the Quoteriser uses for its database management functions
gnurx.zip
The GNU Rx regular expression library. It is probably possible to substitute another regular expression library without undue difficulty, if the reader already has one installed on their system - see Using another regular expression library below. This is not required for non-OS/2 compilation.

Note that OS/2 GNU dbm and GNU Rx may not be able to be used out of the box; check the compile notes below.

The Quoteriser also comes packaged with the author's xtype library (in the xtype sub-directory), which is documented separately. This library should be installed before attempting to install the Quoteriser.

Of course, the reader will also require compilers, linkers and other standard development tools. The author assumes that the reader has all these things installed, given that he or she has set him- or herself to compile a program.


Manifest

Here is a list of all the source files that make up the Quoteriser, and a brief description of what they are:
build.cmd - OS/2 build script for EMX and GNU make
Makefile - OS/2 make file (pre-configured for EMX and GNU make)
Makefile.unx - generic make file (pre-configured for Unix ELF GCC)
include\authors.h - header file for author manipulation routines
include\general.h - header file for miscellaneous routines
include\html.h - header file for HTML parsing routines
include\pmutil.h - header file for miscellaneous PM routines
include\qotd.h - header file for Quote-of-the-day program
include\quoter.h - header file for main Quoteriser program
include\quoterc.h - header file for database compilation routines
include\quotes.h - header file for quote manipulation routines
include\threads.h - header file for threads
include\types.h - some type definitions for the main program
include\typeset.h - header file for typesetting routines
src\qotd.def - definition file for qotd.exe
src\quoter.def - definition file for quoter.exe
src\quoter1.def - definition file for quoter1.dll (normal version)
src\quoter1d.def - definition file for quoter1.dll (debug version)
src\quoterc.def - definition file for quoterc.exe
src\quoterdb.def - definition file for quoterdb.dll
src\quoterla.def - definition file for quoterla.dll
src\sig.def - definition file for sig.exe
src\adlg.rc - author dialogue box resources
src\qdlg.rc - quote dialogue box resources
src\qotd.rc - Quote-of-the-day resources
src\quoter.rc - miscellaneous main program resources
src\settings.rc - settings dialogue box resources
src\adb.c - author database routines
src\adlg.c - author dialogue and menu routines
src\asearch.c - author searching routines
src\athreads.c - threads for dealing with authors
src\authors.c - author manipulation routines
src\dir.c - path name manipulation utilities
src\html.c - basic HTML parsing routines
src\htmlattr.c - HTML tag attribute parsing routines
src\pmscroll.c - scroll bar utilities
src\pmspawn.c - process management utilities
src\qccmd.c - compiler command file routines
src\qcdata.c - compiler data file routines
src\qdb.c - quote database routines
src\qdlg.c - quote dialogue and menu routines
src\qotd.c - Quote-of-the-day main program
src\qotd_p.c - Quote-of-the-day painting routines
src\qsearch.c - quote searching routines
src\qthreads.c - threads for dealing with quotes
src\quoter.c - Quoteriser main program
src\quoterc.c - database compiler main program
src\quoter_p.c - Quoteriser main program painting routines
src\quotes.c - quote manipulation routines
src\settings.c - settings dialogue routines and utilities
src\sig.c - signature generator main program
src\str.c - string manipulation routines
src\typeset.c - HTML typesetting routines
etc\quoter.ico - Quoteriser icon
etc\gdbm.pat - patch to fix OS/2 GDBM's make file
etc\gnurx.pat - patch to alter OS/2 GNU Rx's make file
xtype\* - xtype library, documented separately; pre-configured for EMX/GCC


Compile Notes

The author hopes that the reader will find compiling the Quoteriser will be a relatively painless process, regardless of which compiler and make utility is used, and the layout of the reader's system.

The Quoteriser was developed with the EMX/GCC C compiler and GNU Make, using the standard resource compiler that comes with OS/2. If the reader is using this combination, he or she is in luck and should have to do a very small amount of work. The truly fortunate will simply have to run the build script provided. Otherwise, some things will need to be tweaked.

The OS/2 compilation process is straightforward. All the .c files are compiled into object files. Import libraries for the DLLs are formed from the .def files using an import library generator ('implib', apparently, on most systems, but 'emximp' for EMX). The appropriate object and library files are then linked into .exe and .dll files.

The C library functions are put into the quoter1.dll library (so that the binary distribution doesn't require users to have the EMX run-time libraries to be installed). As the author has no experience with other compilers, he does not have the slightest idea how other compilers feel about this or how they handle their library functions. For this, the reader is on his or her own.

The non-OS/2 process is similar, except that all the common code is put into a library called 'quoter', which is then linked with the main programs.

The make file is very Unix in that it uses forward slashes for directory separators. This is because EMX and GNU Make prefer it this way, and because the author likes to separate the directory separator from the escape character. If the reader's compiler/make don't like this, do a global search-and-replace to change all the forward slashes to back slashes.

Before trying to compile the Quoteriser, the reader should install the xtype library. How to do this is described in separate documentation in the xtype sub-directory. The OS/2 build script provided will do this automatically, but note that everything is pre-configured for EMX and GNU Make, and that EMX is installed in \emx on the current drive.

Before trying to compile the OS/2 Quoteriser, the reader should read at least the sections on the GNU libraries and ensure that they are installed correctly. Unfortunately, unzipping the packages and typing 'make' may not be good enough to get them working. EMX users may also wish to read the minimal Quoteriser section (and, for all the author knows, this section might be useful to other users).

Non-OS/2 users should read the section on systems other than OS/2 below.

Compilers other than EMX

As the Quoteriser has been written as much as possible using only standard C and OS/2 API calls, compilation with a different compiler should be straightforward. The only non-standard C functions used are _beginthread() and stat().

All OS/2 compilers (that this author has heard of) have _beginthread(), though some do not have what is the second argument in EMX' implementation (which serves no purpose and is always NULL). If the reader's compiler is one of the latter sort, simply remove the dud argument from all the _beginthread() calls. EMX does not like the DosCreateThread() API call, hence the use of _beginthread().

The stat() function is a common Unix function that is hopefully available on the reader's compiler. If not, he or she will need to re-write the QuoteDBStat() and AuthorDBStat() functions to avoid the use of stat(). The author hopes to eliminate the calls to stat() in future versions, though implementing this in standard C is likely to be a little messy.

Obviously, the options to pass to the compiler will change from compiler to compiler. Edit the make file to set these options appropriately; the comments in the make file list what all the macros mean.

Make utilities other than GNU

Using another make utility should be relatively painless. The reader will need to alter the pattern rules to use his or her make's syntax. The meanings of the GNU make automatic variables used are as follows:

The automatic variables should be replaced with the equivalent for the reader's make utility.

Some makes may not define the $(MAKE) macro used for calling make recursively; if not, replace this with the name of the make in question.

DMAKE has trouble with shell commands in make files; it needs to be told by putting 'cmd' in front of shell commands like 'if' and 'del'; this may require some work around the clean-objs and spotless-exes section of the make file.

What might need to be changed

Other than translating the make file for the reader's make and possibly altering the code for other compilers, there may still be a few things to do.

The standard version of the code assumes that the headers for the two GNU libraries are <gnu/*.h>;. If the system has them somewhere else, this will need to be changed. The files that are compiled into quoterdb.dll are the ones that will need to be changed (sed should do the trick nicely).

The user may wish to, or may need to, change the names of programs used and options passed to them in the make file. Go through the first four blocks in the make file, (up to and including the targets) changing the values of macros as desired/necessary, according to the meaning of the macro shown in the comment.

Check that the pattern rules are suitable for the compiler being used. Some compilers may prefer using slashes instead of dashes for denoting options, and some compilers may have different names for -o (name of output file) and -c (compile only).

GNU database manager

There is a bug in at least one version of GDBM for OS/2 (the version on ftp.leo.org, I believe) that will cause the Quoteriser to fail during compilation. If the linker complains that there is an undefined symbol 'gdbm_exists', this is why.

The make file packaged with GDBM omits gdbmexists.c and gdbmexist.o from the compilation process. This is trivial to fix, of course. The file etc/gdbm.pat is a patch to fix the version of the make file that the author has. Either fix the make file manually, or run gpatch Makefile.os2 < gdbm.pat if GNU patch ('gpatch', to distinguish it from OS/2's 'patch') is installed. Re-compile the library and everything should be okay.

GNU Rx

GNU Rx for OS/2, out of the box, requires the EMX run-time libraries (emxrt.zip) to be installed. If these are installed, then the reader doesn't have to worry about this - but beware that the re-compiled Quoteriser will need gnurx.dll to be present somewhere in the LIBPATH if this is the case. Just make sure the rx.lib import library and the header files are in the right place, and go.

The standard binary distribution statically links GNU Rx so that the EMX run-time libraries are not required. To do so, GNU Rx has to be re-compiled as a static library instead of a dynamic one (i.e. use 'ar' or whatever instead of 'implib'). Again, this should be fairly simple if the reader knows what he or she is doing. The author's patch for the makefile is in etc/gnurx.pat. Running gpatch Makefile.os2 < gnurx.pat with GNU patch will fix the make file for EMX. Re-compile and go.


Using another regular expression library

There are other regular expression libraries around that will work just as well as GNU Rx. A popular choice is Henry Spencer's library (regexp.tar.gz). EMX users will find that this library is shipped with EMX (as regexp.lib).

To use a different regular expression library, the make file and the files asearch.c, qsearch.c, quotes.h and authors.h will need to be changed. It is also possible that quoter1.def will need to be changed (as the new library might require different C library functions).

In the make file, change the occurrences of 'rx$(L)' to the name of the new regular expression library ('regexp$(L)' for Henry Spencer).

In the source and header files, replace <gnu/rxall.h> and <gnu/rxposix.h> with the header file(s) for the new library (<regexp.h> for Henry Spencer). It may also be necessary to alter the calls to regcomp(), regexec() and regfree() functions if the libary has a different view of things to GNU Rx.

Lastly, if the link now complains about C library functions missing, add these functions to quoter1.def and try again.


A minimal Quoteriser

EMX users can greatly reduce the size of their Quoteriser executables by taking advantage of the EMX run-time libraries (emxrt.zip). To do so, GNU Rx should be compiled as the original dynamic library (and have gnurx.dll in the LIBPATH) and not the static library used in the standard distribution.

Alter the makefile so that -Zcrtdll is passed to every linking stage; i.e. remove the '=quoter1' stuff. Change the LCFLAGS macro to be the same as the LLFLAGS macro.

Now, get rid of all the C library stuff in quoter1.def; i.e. the stuff below the line that says 'Everything below this line is imported from the EMX run-time libraries...'. (Actually, the quoter1d.def file is already like this.)

Now re-compile and a good 120k or more should be removed from the resulting executables.


Systems other than OS/2

As of Version 2.10, a subset of Quoteriser programs (sig and quoterc) are available for compilation under systems other than OS/2 using the GENERIC macro. The main Quoteriser program and the quote-of-the-day utility use OS/2 Presentation Manager API calls and therefore cannot be compiled for other systems.

Defining GENERIC at compile time #ifdef's out any OS/2-specific code from the source files required to build the signature generator and the database compiler. The code that remains is strict POSIX/ANSI C, except for the use of the stat() library function in QuoteDBStat() and AuthorDBStat(). Every compiler this author has seen has stat(); if the reader's does not, he or she will have to re-write these two functions.

The Makefile.unx file shipped with the Quoteriser source code is designed to be readily converted for compilation on any sensible system. It has been pre-configured for Unix ELF GCC, and has been tested under Linux and Solaris using this configuration. The author expects that modifying it for other Unix configurations should be trivial.

Before compiling, read the What might need to be changed section above.


Help

If the reader is having trouble with compiling the Quoteriser, and has exhausted all the help in this file, the author is happy to help in any way he can. Remember, though, that he can't answer questions about specifics of compilers other than EMX or makes other than GNU. RTFM.

If the author can make changes to future releases of the Quoteriser that would make the reader's life easier (without hurting anyone else, of course), he would be most happy to incorporate them. This might be by getting rid of stat(), providing some extra macros in the make file, etc.

If the reader can help the author make the Quoteriser easier to transport between compilers, he or she is most welcome to help. Alternative make files, quoter1.defs, etc., for other compilers can be submitted to the author at nps@zeta.org.au. The usual addition to the credits and warm, fuzzy feeling applies.

Happy compiling.