diff options
Diffstat (limited to 'Master/xemtex/doc/ghostscript/Source.htm')
-rw-r--r-- | Master/xemtex/doc/ghostscript/Source.htm | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/Master/xemtex/doc/ghostscript/Source.htm b/Master/xemtex/doc/ghostscript/Source.htm new file mode 100644 index 00000000000..348920b4e22 --- /dev/null +++ b/Master/xemtex/doc/ghostscript/Source.htm @@ -0,0 +1,383 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<title>Guide to Ghostscript source code</title> +<!-- $Id: Source.htm,v 1.13.2.11.2.5 2003/05/17 14:39:00 giles Exp $ --> +<!-- Originally: source.txt --> +<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> +</head> + +<body> +<!-- [1.0 begin visible header] ============================================ --> + +<!-- [1.1 begin headline] ================================================== --> + +<h1>Guide to Ghostscript source code</h1> + +<!-- [1.1 end headline] ==================================================== --> + +<!-- [1.2 begin table of contents] ========================================= --> + +<h2>Table of contents</h2> + +<blockquote><ul> +<li><a href="#Overview">Conceptual overview</a> +<li><a href="#PostScript_interpreter">PostScript Interpreter</a> +<li><a href="#PDF_interpreter">PDF interpreter</a> +<li><a href="#Graphics_library">Graphics library</a> +<ul> +<li><a href="#Drivers">Device drivers</a> +<li><a href="#Platform_specific_code">Platform-specific code</a> +</ul> +<li><a href="#Makefiles">Makefiles</a> +</ul></blockquote> + +<!-- [1.2 end table of contents] =========================================== --> + +<!-- [1.3 begin hint] ====================================================== --> + +<p>For other information, see the <a href="Readme.htm">Ghostscript +overview</a> and the documents on <a href="Make.htm">how to build +Ghostscript</a> from source, <a href="C-style.htm">Ghostscript C coding +guidelines</a>, <a href="Drivers.htm">drivers</a>, the +<a href="Lib.htm">Ghostscript library</a> and <a href="Install.htm">how to +install Ghostscript</a>. + +<!-- [1.3 end hint] ======================================================== --> + +<hr> + +<!-- [1.0 end visible header] ============================================== --> + +<!-- [2.0 begin contents] ================================================== --> + +<h2><a name="Overview"></a>Conceptual overview</h2> + +<p> +The Ghostscript source code is divided conceptually as follows: + +<blockquote><table cellpadding=0 cellspacing=0> +<tr valign=top> <th align=left colspan=4><a href="#PostScript_interpreter">PostScript interpreter</a>: +<tr valign=top> <td> + <td>PostScript operators + <td> + <td><b><tt>z</tt></b>*<b><tt>.h</tt></b> and <b><tt>z</tt></b>*<b><tt>.c</tt></b> +<tr valign=top> <td> + <td>Other interpreter code + <td> + <td><b><tt>i</tt></b>*<b><tt>.h</tt></b> and <b><tt>i</tt></b>*<b><tt>.c</tt></b> +<tr valign=top> <td> + <td>PostScript code + <td> + <td><b><tt>gs_</tt></b>*<b><tt>.ps</tt></b> +<tr valign=top> <th align=left colspan=4><a href="#PDF_interpreter">PDF interpreter</a>: +<tr valign=top> <td> + <td>PostScript code + <td> + <td><b><tt>pdf_</tt></b>*<b><tt>.ps</tt></b> +<tr valign=top> <th align=left colspan=4><a href="#Graphics_library">Graphics library</a>: +<tr valign=top> <td> + <td>Main library code + <td> + <td><b><tt>g</tt></b>*<b><tt>.h</tt></b> and <b><tt>g</tt></b>*<b><tt>.c</tt></b> +<tr valign=top> <td> + <td>Streams + <td> + <td><b><tt>s</tt></b>*<b><tt>.h</tt></b> and <b><tt>s</tt></b>*<b><tt>.c</tt></b> +<tr valign=top> <td> + <td><a href="#Drivers">Device drivers</a> + <td> + <td><b><tt>gdev</tt></b>*<b><tt>.h</tt></b> and <b><tt>gdev</tt></b>*<b><tt>.c</tt></b> +<tr valign=top> <td> + <td><a href="#Platform_specific_code">Platform-specific code</a> + <td> + <td><b><tt>gp</tt></b>*<b><tt>.h</tt></b> and <b><tt>gp</tt></b>*<b><tt>.c</tt></b> +</table></blockquote> + +<hr> + +<h2><a name="PostScript_interpreter"></a>PostScript Interpreter</h2> + +<p> +<b><tt>gs.c</tt></b> is the main program for the interactive language +interpreter; <b><tt>gserver.c</tt></b> is an alternative main program that +is a rudimentary server. If you configure Ghostscript as a server rather +than an interactive program, you will use <b><tt>gserver.c</tt></b> instead +of <b><tt>gs.c</tt></b>. + +<p> +Files named <b><tt>z</tt></b>*<b><tt>.c</tt></b> are Ghostscript operator +files. The names of the files generally follow the section headings of the +operator summary in section 6.2 (Second Edition) or 8.2 (Third Edition) of +the PostScript Language Reference Manual. Each operator XXX is implemented +by a procedure named <b><tt>z</tt></b>XXX, for example, +<b><tt>zfill</tt></b> and <b><tt>zarray</tt></b>. + +<p> +Files named <b><tt>i</tt></b>*<b><tt>.c</tt></b>, and *<b><tt>.h</tt></b> +other than <b><tt>g</tt></b>*<b><tt>.h</tt></b>, are the rest of the +interpreter. See the makefile for a little more information on how the +files are divided functionally. + +<p> +The main loop of the PostScript interpreter is the <b><tt>interp</tt></b> +procedure in <b><tt>interp.c</tt></b>. When the interpreter is reading +from an input file, it calls the token scanner in +<b><tt>iscan</tt></b>*<b><tt>.c</tt></b>. + +<p> +<b><tt>idebug.c</tt></b> contains a lot of debugger-callable routines +useful for printing PostScript objects when debugging. + +<hr> + +<h2><a name="PDF_interpreter"></a>PDF interpreter</h2> + +<p> +The PDF interpreter is written entirely in PostScript. Its main loop is +the <b><tt>.pdfrun</tt></b> procedure in <b><tt>pdf_base.ps</tt></b>. When +the PDF interpreter is configured into the build, it redefines the +"<b><tt>run</tt></b>" operator to test whether the file is a PDF file. +This redefinition is near the beginning of <b><tt>pdf_main.ps</tt></b>. + +<hr> + +<h2><a name="Graphics_library"></a>Graphics library</h2> + +<p> +Files beginning with <b><tt>gs</tt></b>, <b><tt>gx</tt></b>, or +<b><tt>gz</tt></b> (both <b><tt>.c</tt></b> and <b><tt>.h</tt></b>), other +than <b><tt>gs.c</tt></b> and <b><tt>gserver.c</tt></b>, are the +Ghostscript library. Files beginning with <b><tt>gdev</tt></b> are device +drivers or related code, also part of the library. Other files beginning +with <b><tt>g</tt></b> are library files that don't fall neatly into either +the kernel or the driver category. + +<p> +Files named <b><tt>s</tt></b>*<b><tt>.c</tt></b> and +<b><tt>s</tt></b>*<b><tt>.h</tt></b> are a flexible stream package, +including the Level 2 PostScript "filters" supported by Ghostscript. See +<b><tt>stream.h</tt></b>, <b><tt>scommon.h</tt></b>, and +<b><tt>strimpl.h</tt></b> for all the details. + +<h3><a name="Drivers"></a>Device drivers</h3> + +<p> +The interface between the graphics library and device drivers is the only +really well documented one in all of Ghostscript: see the +<a href="Drivers.htm">documentation on drivers</a>. + +<p> +In addition to many real device and file format drivers listed in +<b><tt>devs.mak</tt></b> and <b><tt>contrib.mak</tt></b>, a number of +drivers are used for internal purposes. You can search +<b><tt>lib.mak</tt></b> for files named +<b><tt>gdev</tt></b>*<b><tt>.c</tt></b> to find almost all of them. + +<p> +Drivers are divided into "printer" drivers, which support banding, and +non-printer drivers, which don't. The decision whether banding is +required is made (by default on the basis of how much memory is available) +in the procedure <b><tt>gdev_prn_alloc</tt></b> in +<b><tt>gdevprn.c</tt></b>: it implements this decision by filling the +virtual procedure table for the printer device in one of two different +ways. + +<p> +A good simple "printer" (bandable) driver to read is +<b><tt>gdevmiff.c</tt></b>: it's less than 100 lines, of which much is +boilerplate. There are no simple non-printer drivers that actually drive +devices: probably the simplest non-printer driver for reading is +<b><tt>gdevm8.c</tt></b>, which implements 8-bit-deep devices that only +store the bits in memory. + +<h3><a name="Platform_specific_code"></a>Platform-specific code</h3> + +<p> +There are very few platform dependencies in Ghostscript. Ghostscript deals +with them in three ways: + +<ul> +<li>Files named *<b><tt>_.h</tt></b> substitute for the corresponding +<b><tt><</tt></b>*<b><tt>.h></tt></b> file by adding conditionals +that provide a uniform set of system interfaces on all platforms. + +<li>The file <b><tt>arch.h</tt></b> contains a set of +mechanically-discovered platform properties like byte order, size of +<b><tt>int</tt></b>, etc. These properties, <b>not</b> the names of +specific platforms, are used to select between different algorithms or +parameters at compile time. + +<li>Files named <b><tt>gp</tt></b>*<b><tt>.h</tt></b> define interfaces +that are intended to be implemented differently on each platform, but whose +specification is common to all platforms. +</ul> + +<p> +The platform-specific implementations of the +<b><tt>gp</tt></b>*<b><tt>.h</tt></b> interfaces have names of the form +"<b><tt>gp_</tt></b><em>{platform}</em><b><tt>.c</tt></b>, specifically +(this list may be out of date): + +<blockquote><table cellpadding=0 cellspacing=0> +<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Platform-specific interfaces</font><hr> +<tr valign=bottom> + <th align=left>Routine + <td> + <th align=left>Platform +<tr> <td colspan=3><hr> +<tr valign=top> <td><b><tt>gp_dosfb.c</tt></b> + <td> + <td>DOS +<tr valign=top> <td><b><tt>gp_dosfs.c</tt></b> + <td> + <td>DOS and MS Windows +<tr valign=top> <td><b><tt>gp_itbc.c</tt></b> + <td> + <td>DOS, Borland compilers +<tr valign=top> <td><b><tt>gp_iwatc.c</tt></b> + <td> + <td>DOS, Watcom or Microsoft compiler +<tr valign=top> <td><b><tt>gp_msdos.c</tt></b> + <td> + <td>DOS and MS Windows +<tr valign=top> <td><b><tt>gp_ntfs.c</tt></b> + <td> + <td>MS-Windows Win32s and Windows NT +<tr valign=top> <td><b><tt>gp_os2.c</tt></b> + <td> + <td>OS/2 +<tr valign=top> <td><b><tt>gp_os9.c</tt></b> + <td> + <td>OS-9 +<tr valign=top> <td><b><tt>gp_unifs.c</tt></b> + <td> + <td>Unix, OS-9, and QNX +<tr valign=top> <td><b><tt>gp_unix.c</tt></b> + <td> + <td>Unix and QNX +<tr valign=top> <td><b><tt>gp_sysv.c</tt></b> + <td> + <td>System V Unix +<tr valign=top> <td><b><tt>gp_vms.c</tt></b> + <td> + <td>VMS +<tr valign=top> <td><b><tt>gp_win32.c</tt></b> + <td> + <td>MS-Windows Win32s and Windows NT +</table></blockquote> + +<p> +If you are going to extend Ghostscript to new machines or operating +systems, check the *<b><tt>_.h</tt></b> files for <b><tt>ifdef</tt></b> on +things other than <b><tt>DEBUG</tt></b>. You should probably plan to make +a new makefile and a new <b><tt>gp_</tt></b>XXX<b><tt>.c</tt></b> file. + +<hr> + +<h2><a name="Makefiles"></a>Makefiles</h2> + +<p> +This section is only for advanced developers who need to integrate +Ghostscript into a larger program at build time. + +<p> +NOTE: THIS SECTION IS INCOMPLETE. IT WILL BE IMPROVED IN A LATER REVISION. + +<p> +The Ghostscript makefiles are meant to be organized according to the +following two principles: + +<ul> + +<li>All the parameters that vary from platform to platform appear in the +top-level makefile for a given platform. ("Platform" = OS + compiler + +choice of interpreter vs. library) + +<li>All the rules and definitions that can meaningfully be shared among more +than 1 platform appear in a makefile that is "included" by a makefile +(normally the top-level makefile) for those platforms. +</ul> + +<p> +Thus, for example: + +<ul> + +<li>Rules and definitions shared by all builds are in +<b><tt>gs.mak</tt></b>. + +<li>Rules and definitions specific to the library (on all platforms) are in +<b><tt>lib.mak</tt></b>. In principle this could be merged with +<b><tt>gs.mak</tt></b>, but we wanted to leave open the possibility that +<b><tt>gs.mak</tt></b> might be useful with hypothetical interpreter-only +products. + +<li>Stuff specific to interpreters (on all platforms) is in +<b><tt>int.mak</tt></b>. + +<li>Stuff specific to all Unix platforms should be in a single +<b><tt>unix.mak</tt></b> file, but because <b><tt>make</tt></b> sometimes +cares about the order of definitions, and because some of it is shared with +DV/X, it got split between <b><tt>unix-aux.mak</tt></b>, +<b><tt>unix-end.mak</tt></b>, <b><tt>unixhead.mak</tt></b>, +<b><tt>unixinst.mak</tt></b>, and <b><tt>unixlink.mak</tt></b>. + +</ul> + +<p> +For MS-DOS and MS Windows builds, there should be: + +<ul> + +<li>A makefile for all MS OS (DOS or Windows) builds, for all + compilers and products. + +<li>Perhaps a makefile for all MS-DOS builds, for all compilers and +products, although since Watcom is the only such compiler we're likely to +support this may be overkill. + +<li>A makefile for all MS Windows builds, for all compilers and products. + +<li>A makefile for all Watcom builds (DOS or Windows), for all products. + +<li>A top-level makefile for the Watcom DOS interpreter product. + +<li>A top-level makefile for the Watcom Windows interpreter product. + +<li>A top-level makefile for the Watcom DOS library "product". + +<li>A top-level makefile for the Watcom Windows library "product". + +<li>A makefile for all Borland builds (DOS or Windows), for all + products. + +</ul> + +<p> +and so on. + +<!-- [2.0 end contents] ==================================================== --> + +<!-- [3.0 begin visible trailer] =========================================== --> +<hr> + +<p> +<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises. All +rights reserved.</small> + +<p> +This software is provided AS-IS with no warranty, either express or +implied. + +This software is distributed under license and may not be copied, +modified or distributed except as expressly authorized under the terms +of the license contained in the file LICENSE in this distribution. + +<p> +<small>Ghostscript version 7.07, 17 May 2003 + +<!-- [3.0 end visible trailer] ============================================= --> + +</body> +</html> |