Contents:
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.
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
gnugdbm.zip
gnurx.zip
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.
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 |
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.
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.
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:
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
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
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).
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
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
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 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().
Make utilities other than GNU
The automatic variables should be replaced with the equivalent for the reader's
make utility.
$<
- the name of the first dependency in the list (the 'source file')
$^
- all the dependencies in the list
$@
- the name of the target file
clean-objs
and spotless-exes
section of the make file.
What might need to be changed
<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).
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.
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.
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.
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.
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.
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.def
s, 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.