| 2 |
- |
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<title>Guide to Ghostscript source code</title>
|
|
|
5 |
<!-- $Id: Source.htm,v 1.39 2005/10/20 19:46:23 ray Exp $ -->
|
|
|
6 |
<!-- Originally: source.txt -->
|
|
|
7 |
<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
|
|
|
8 |
</head>
|
|
|
9 |
|
|
|
10 |
<body>
|
|
|
11 |
<!-- [1.0 begin visible header] ============================================ -->
|
|
|
12 |
|
|
|
13 |
<!-- [1.1 begin headline] ================================================== -->
|
|
|
14 |
|
|
|
15 |
<h1>Guide to Ghostscript source code</h1>
|
|
|
16 |
|
|
|
17 |
<!-- [1.1 end headline] ==================================================== -->
|
|
|
18 |
|
|
|
19 |
<!-- [1.2 begin table of contents] ========================================= -->
|
|
|
20 |
|
|
|
21 |
<h2>Table of contents</h2>
|
|
|
22 |
|
|
|
23 |
<blockquote><ul>
|
|
|
24 |
<li><a href="#Overview">Conceptual overview</a>
|
|
|
25 |
<li><a href="#PostScript_interpreter">PostScript Interpreter</a>
|
|
|
26 |
<li><a href="#PDF_interpreter">PDF interpreter</a>
|
|
|
27 |
<li><a href="#Graphics_library">Graphics library</a>
|
|
|
28 |
<ul>
|
|
|
29 |
<li><a href="#Drivers">Device drivers</a>
|
|
|
30 |
<li><a href="#Platform_specific_code">Platform-specific code</a>
|
|
|
31 |
</ul>
|
|
|
32 |
<li><a href="#Makefiles">Makefiles</a>
|
|
|
33 |
</ul></blockquote>
|
|
|
34 |
|
|
|
35 |
<!-- [1.2 end table of contents] =========================================== -->
|
|
|
36 |
|
|
|
37 |
<!-- [1.3 begin hint] ====================================================== -->
|
|
|
38 |
|
|
|
39 |
<p>For other information, see the <a href="Readme.htm">Ghostscript
|
|
|
40 |
overview</a> and the documents on <a href="Make.htm">how to build
|
|
|
41 |
Ghostscript</a> from source, <a href="C-style.htm">Ghostscript C coding
|
|
|
42 |
guidelines</a>, <a href="Drivers.htm">drivers</a>, the
|
|
|
43 |
<a href="Lib.htm">Ghostscript library</a> and <a href="Install.htm">how to
|
|
|
44 |
install Ghostscript</a>.
|
|
|
45 |
|
|
|
46 |
<!-- [1.3 end hint] ======================================================== -->
|
|
|
47 |
|
|
|
48 |
<hr>
|
|
|
49 |
|
|
|
50 |
<!-- [1.0 end visible header] ============================================== -->
|
|
|
51 |
|
|
|
52 |
<!-- [2.0 begin contents] ================================================== -->
|
|
|
53 |
|
|
|
54 |
<h2><a name="Overview"></a>Conceptual overview</h2>
|
|
|
55 |
|
|
|
56 |
<p>
|
|
|
57 |
The Ghostscript source code is divided conceptually as follows:
|
|
|
58 |
|
|
|
59 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
60 |
<tr valign=top> <th align=left colspan=4><a href="#PostScript_interpreter">PostScript interpreter</a>:
|
|
|
61 |
<tr valign=top> <td>
|
|
|
62 |
<td>PostScript operators
|
|
|
63 |
<td>
|
|
|
64 |
<td><b><tt>z</tt></b>*<b><tt>.h</tt></b> and <b><tt>z</tt></b>*<b><tt>.c</tt></b>
|
|
|
65 |
<tr valign=top> <td>
|
|
|
66 |
<td>Other interpreter code
|
|
|
67 |
<td>
|
|
|
68 |
<td><b><tt>i</tt></b>*<b><tt>.h</tt></b> and <b><tt>i</tt></b>*<b><tt>.c</tt></b>
|
|
|
69 |
<tr valign=top> <td>
|
|
|
70 |
<td>PostScript code
|
|
|
71 |
<td>
|
|
|
72 |
<td><b><tt>gs_</tt></b>*<b><tt>.ps</tt></b>
|
|
|
73 |
<tr valign=top> <th align=left colspan=4><a href="#PDF_interpreter">PDF interpreter</a>:
|
|
|
74 |
<tr valign=top> <td>
|
|
|
75 |
<td>PostScript code
|
|
|
76 |
<td>
|
|
|
77 |
<td><b><tt>pdf_</tt></b>*<b><tt>.ps</tt></b>
|
|
|
78 |
<tr valign=top> <th align=left colspan=4><a href="#Graphics_library">Graphics library</a>:
|
|
|
79 |
<tr valign=top> <td>
|
|
|
80 |
<td>Main library code
|
|
|
81 |
<td>
|
|
|
82 |
<td><b><tt>g</tt></b>*<b><tt>.h</tt></b> and <b><tt>g</tt></b>*<b><tt>.c</tt></b>
|
|
|
83 |
<tr valign=top> <td>
|
|
|
84 |
<td>Streams
|
|
|
85 |
<td>
|
|
|
86 |
<td><b><tt>s</tt></b>*<b><tt>.h</tt></b> and <b><tt>s</tt></b>*<b><tt>.c</tt></b>
|
|
|
87 |
<tr valign=top> <td>
|
|
|
88 |
<td><a href="#Drivers">Device drivers</a>
|
|
|
89 |
<td>
|
|
|
90 |
<td><b><tt>gdev</tt></b>*<b><tt>.h</tt></b> and <b><tt>gdev</tt></b>*<b><tt>.c</tt></b>
|
|
|
91 |
<tr valign=top> <td>
|
|
|
92 |
<td><a href="#Platform_specific_code">Platform-specific code</a>
|
|
|
93 |
<td>
|
|
|
94 |
<td><b><tt>gp</tt></b>*<b><tt>.h</tt></b> and <b><tt>gp</tt></b>*<b><tt>.c</tt></b>
|
|
|
95 |
</table></blockquote>
|
|
|
96 |
|
|
|
97 |
<hr>
|
|
|
98 |
|
|
|
99 |
<h2><a name="PostScript_interpreter"></a>PostScript Interpreter</h2>
|
|
|
100 |
|
|
|
101 |
<p>
|
|
|
102 |
<b><tt>gs.c</tt></b> is the main program for the interactive language
|
|
|
103 |
interpreter; <b><tt>gserver.c</tt></b> is an alternative main program that
|
|
|
104 |
is a rudimentary server. If you configure Ghostscript as a server rather
|
|
|
105 |
than an interactive program, you will use <b><tt>gserver.c</tt></b> instead
|
|
|
106 |
of <b><tt>gs.c</tt></b>.
|
|
|
107 |
|
|
|
108 |
<p>
|
|
|
109 |
Files named <b><tt>z</tt></b>*<b><tt>.c</tt></b> are Ghostscript operator
|
|
|
110 |
files. The names of the files generally follow the section headings of the
|
|
|
111 |
operator summary in section 6.2 (Second Edition) or 8.2 (Third Edition) of
|
|
|
112 |
the PostScript Language Reference Manual. Each operator XXX is implemented
|
|
|
113 |
by a procedure named <b><tt>z</tt></b>XXX, for example,
|
|
|
114 |
<b><tt>zfill</tt></b> and <b><tt>zarray</tt></b>.
|
|
|
115 |
|
|
|
116 |
<p>
|
|
|
117 |
Files named <b><tt>i</tt></b>*<b><tt>.c</tt></b>, and *<b><tt>.h</tt></b>
|
|
|
118 |
other than <b><tt>g</tt></b>*<b><tt>.h</tt></b>, are the rest of the
|
|
|
119 |
interpreter. See the makefile for a little more information on how the
|
|
|
120 |
files are divided functionally.
|
|
|
121 |
|
|
|
122 |
<p>
|
|
|
123 |
The main loop of the PostScript interpreter is the <b><tt>interp</tt></b>
|
|
|
124 |
procedure in <b><tt>interp.c</tt></b>. When the interpreter is reading
|
|
|
125 |
from an input file, it calls the token scanner in
|
|
|
126 |
<b><tt>iscan</tt></b>*<b><tt>.c</tt></b>.
|
|
|
127 |
|
|
|
128 |
<p>
|
|
|
129 |
<b><tt>idebug.c</tt></b> contains a lot of debugger-callable routines
|
|
|
130 |
useful for printing PostScript objects when debugging.
|
|
|
131 |
|
|
|
132 |
<hr>
|
|
|
133 |
|
|
|
134 |
<h2><a name="PDF_interpreter"></a>PDF interpreter</h2>
|
|
|
135 |
|
|
|
136 |
<p>
|
|
|
137 |
The PDF interpreter is written entirely in PostScript. Its main loop is
|
|
|
138 |
the <b><tt>.pdfrun</tt></b> procedure in <b><tt>pdf_base.ps</tt></b>. When
|
|
|
139 |
the PDF interpreter is configured into the build, it redefines the
|
|
|
140 |
"<b><tt>run</tt></b>" operator to test whether the file is a PDF file.
|
|
|
141 |
This redefinition is near the beginning of <b><tt>pdf_main.ps</tt></b>.
|
|
|
142 |
|
|
|
143 |
<hr>
|
|
|
144 |
|
|
|
145 |
<h2><a name="Graphics_library"></a>Graphics library</h2>
|
|
|
146 |
|
|
|
147 |
<p>
|
|
|
148 |
Files beginning with <b><tt>gs</tt></b>, <b><tt>gx</tt></b>, or
|
|
|
149 |
<b><tt>gz</tt></b> (both <b><tt>.c</tt></b> and <b><tt>.h</tt></b>), other
|
|
|
150 |
than <b><tt>gs.c</tt></b> and <b><tt>gserver.c</tt></b>, are the
|
|
|
151 |
Ghostscript library. Files beginning with <b><tt>gdev</tt></b> are device
|
|
|
152 |
drivers or related code, also part of the library. Other files beginning
|
|
|
153 |
with <b><tt>g</tt></b> are library files that don't fall neatly into either
|
|
|
154 |
the kernel or the driver category.
|
|
|
155 |
|
|
|
156 |
<p>
|
|
|
157 |
Files named <b><tt>s</tt></b>*<b><tt>.c</tt></b> and
|
|
|
158 |
<b><tt>s</tt></b>*<b><tt>.h</tt></b> are a flexible stream package,
|
|
|
159 |
including the Level 2 PostScript "filters" supported by Ghostscript. See
|
|
|
160 |
<b><tt>stream.h</tt></b>, <b><tt>scommon.h</tt></b>, and
|
|
|
161 |
<b><tt>strimpl.h</tt></b> for all the details.
|
|
|
162 |
|
|
|
163 |
<h3><a name="Drivers"></a>Device drivers</h3>
|
|
|
164 |
|
|
|
165 |
<p>
|
|
|
166 |
The interface between the graphics library and device drivers is the only
|
|
|
167 |
really well documented one in all of Ghostscript: see the
|
|
|
168 |
<a href="Drivers.htm">documentation on drivers</a>.
|
|
|
169 |
|
|
|
170 |
<p>
|
|
|
171 |
In addition to many real device and file format drivers listed in
|
|
|
172 |
<b><tt>devs.mak</tt></b> and <b><tt>contrib.mak</tt></b>, a number of
|
|
|
173 |
drivers are used for internal purposes. You can search
|
|
|
174 |
<b><tt>lib.mak</tt></b> for files named
|
|
|
175 |
<b><tt>gdev</tt></b>*<b><tt>.c</tt></b> to find almost all of them.
|
|
|
176 |
|
|
|
177 |
<p>
|
|
|
178 |
Drivers are divided into "printer" drivers, which support banding, and
|
|
|
179 |
non-printer drivers, which don't. The decision whether banding is
|
|
|
180 |
required is made (by default on the basis of how much memory is available)
|
|
|
181 |
in the procedure <b><tt>gdev_prn_alloc</tt></b> in
|
|
|
182 |
<b><tt>gdevprn.c</tt></b>: it implements this decision by filling the
|
|
|
183 |
virtual procedure table for the printer device in one of two different
|
|
|
184 |
ways.
|
|
|
185 |
|
|
|
186 |
<p>
|
|
|
187 |
A good simple "printer" (bandable) driver to read is
|
|
|
188 |
<b><tt>gdevmiff.c</tt></b>: it's less than 100 lines, of which much is
|
|
|
189 |
boilerplate. There are no simple non-printer drivers that actually drive
|
|
|
190 |
devices: probably the simplest non-printer driver for reading is
|
|
|
191 |
<b><tt>gdevm8.c</tt></b>, which implements 8-bit-deep devices that only
|
|
|
192 |
store the bits in memory.
|
|
|
193 |
|
|
|
194 |
<h3><a name="Platform_specific_code"></a>Platform-specific code</h3>
|
|
|
195 |
|
|
|
196 |
<p>
|
|
|
197 |
There are very few platform dependencies in Ghostscript. Ghostscript deals
|
|
|
198 |
with them in three ways:
|
|
|
199 |
|
|
|
200 |
<ul>
|
|
|
201 |
<li>Files named *<b><tt>_.h</tt></b> substitute for the corresponding
|
|
|
202 |
<b><tt><</tt></b>*<b><tt>.h></tt></b> file by adding conditionals
|
|
|
203 |
that provide a uniform set of system interfaces on all platforms.
|
|
|
204 |
|
|
|
205 |
<li>The file <b><tt>arch.h</tt></b> contains a set of
|
|
|
206 |
mechanically-discovered platform properties like byte order, size of
|
|
|
207 |
<b><tt>int</tt></b>, etc. These properties, <b>not</b> the names of
|
|
|
208 |
specific platforms, are used to select between different algorithms or
|
|
|
209 |
parameters at compile time.
|
|
|
210 |
|
|
|
211 |
<li>Files named <b><tt>gp</tt></b>*<b><tt>.h</tt></b> define interfaces
|
|
|
212 |
that are intended to be implemented differently on each platform, but whose
|
|
|
213 |
specification is common to all platforms.
|
|
|
214 |
</ul>
|
|
|
215 |
|
|
|
216 |
<p>
|
|
|
217 |
The platform-specific implementations of the
|
|
|
218 |
<b><tt>gp</tt></b>*<b><tt>.h</tt></b> interfaces have names of the form
|
|
|
219 |
"<b><tt>gp_</tt></b><em>{platform}</em><b><tt>.c</tt></b>, specifically
|
|
|
220 |
(this list may be out of date):
|
|
|
221 |
|
|
|
222 |
<blockquote><table cellpadding=0 cellspacing=0>
|
|
|
223 |
<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Platform-specific interfaces</font><hr>
|
|
|
224 |
<tr valign=bottom>
|
|
|
225 |
<th align=left>Routine
|
|
|
226 |
<td>
|
|
|
227 |
<th align=left>Platform
|
|
|
228 |
<tr> <td colspan=3><hr>
|
|
|
229 |
<tr valign=top> <td><b><tt>gp_dosfb.c</tt></b>
|
|
|
230 |
<td>
|
|
|
231 |
<td>DOS
|
|
|
232 |
<tr valign=top> <td><b><tt>gp_dosfs.c</tt></b>
|
|
|
233 |
<td>
|
|
|
234 |
<td>DOS and MS Windows
|
|
|
235 |
<tr valign=top> <td><b><tt>gp_itbc.c</tt></b>
|
|
|
236 |
<td>
|
|
|
237 |
<td>DOS, Borland compilers
|
|
|
238 |
<tr valign=top> <td><b><tt>gp_iwatc.c</tt></b>
|
|
|
239 |
<td>
|
|
|
240 |
<td>DOS, Watcom or Microsoft compiler
|
|
|
241 |
<tr valign=top> <td><b><tt>gp_msdos.c</tt></b>
|
|
|
242 |
<td>
|
|
|
243 |
<td>DOS and MS Windows
|
|
|
244 |
<tr valign=top> <td><b><tt>gp_ntfs.c</tt></b>
|
|
|
245 |
<td>
|
|
|
246 |
<td>MS-Windows Win32s and Windows NT
|
|
|
247 |
<tr valign=top> <td><b><tt>gp_os2.c</tt></b>
|
|
|
248 |
<td>
|
|
|
249 |
<td>OS/2
|
|
|
250 |
<tr valign=top> <td><b><tt>gp_os9.c</tt></b>
|
|
|
251 |
<td>
|
|
|
252 |
<td>OS-9
|
|
|
253 |
<tr valign=top> <td><b><tt>gp_unifs.c</tt></b>
|
|
|
254 |
<td>
|
|
|
255 |
<td>Unix, OS-9, and QNX
|
|
|
256 |
<tr valign=top> <td><b><tt>gp_unix.c</tt></b>
|
|
|
257 |
<td>
|
|
|
258 |
<td>Unix and QNX
|
|
|
259 |
<tr valign=top> <td><b><tt>gp_sysv.c</tt></b>
|
|
|
260 |
<td>
|
|
|
261 |
<td>System V Unix
|
|
|
262 |
<tr valign=top> <td><b><tt>gp_vms.c</tt></b>
|
|
|
263 |
<td>
|
|
|
264 |
<td>VMS
|
|
|
265 |
<tr valign=top> <td><b><tt>gp_win32.c</tt></b>
|
|
|
266 |
<td>
|
|
|
267 |
<td>MS-Windows Win32s and Windows NT
|
|
|
268 |
</table></blockquote>
|
|
|
269 |
|
|
|
270 |
<p>
|
|
|
271 |
If you are going to extend Ghostscript to new machines or operating
|
|
|
272 |
systems, check the *<b><tt>_.h</tt></b> files for <b><tt>ifdef</tt></b> on
|
|
|
273 |
things other than <b><tt>DEBUG</tt></b>. You should probably plan to make
|
|
|
274 |
a new makefile and a new <b><tt>gp_</tt></b>XXX<b><tt>.c</tt></b> file.
|
|
|
275 |
|
|
|
276 |
<hr>
|
|
|
277 |
|
|
|
278 |
<h2><a name="Makefiles"></a>Makefiles</h2>
|
|
|
279 |
|
|
|
280 |
<p>
|
|
|
281 |
This section is only for advanced developers who need to integrate
|
|
|
282 |
Ghostscript into a larger program at build time.
|
|
|
283 |
|
|
|
284 |
<p>
|
|
|
285 |
NOTE: THIS SECTION IS INCOMPLETE. IT WILL BE IMPROVED IN A LATER REVISION.
|
|
|
286 |
|
|
|
287 |
<p>
|
|
|
288 |
The Ghostscript makefiles are meant to be organized according to the
|
|
|
289 |
following two principles:
|
|
|
290 |
|
|
|
291 |
<ul>
|
|
|
292 |
|
|
|
293 |
<li>All the parameters that vary from platform to platform appear in the
|
|
|
294 |
top-level makefile for a given platform. ("Platform" = OS + compiler +
|
|
|
295 |
choice of interpreter vs. library)
|
|
|
296 |
|
|
|
297 |
<li>All the rules and definitions that can meaningfully be shared among more
|
|
|
298 |
than 1 platform appear in a makefile that is "included" by a makefile
|
|
|
299 |
(normally the top-level makefile) for those platforms.
|
|
|
300 |
</ul>
|
|
|
301 |
|
|
|
302 |
<p>
|
|
|
303 |
Thus, for example:
|
|
|
304 |
|
|
|
305 |
<ul>
|
|
|
306 |
|
|
|
307 |
<li>Rules and definitions shared by all builds are in
|
|
|
308 |
<b><tt>gs.mak</tt></b>.
|
|
|
309 |
|
|
|
310 |
<li>Rules and definitions specific to the library (on all platforms) are in
|
|
|
311 |
<b><tt>lib.mak</tt></b>. In principle this could be merged with
|
|
|
312 |
<b><tt>gs.mak</tt></b>, but we wanted to leave open the possibility that
|
|
|
313 |
<b><tt>gs.mak</tt></b> might be useful with hypothetical interpreter-only
|
|
|
314 |
products.
|
|
|
315 |
|
|
|
316 |
<li>Stuff specific to interpreters (on all platforms) is in
|
|
|
317 |
<b><tt>int.mak</tt></b>.
|
|
|
318 |
|
|
|
319 |
<li>Stuff specific to all Unix platforms should be in a single
|
|
|
320 |
<b><tt>unix.mak</tt></b> file, but because <b><tt>make</tt></b> sometimes
|
|
|
321 |
cares about the order of definitions, and because some of it is shared with
|
|
|
322 |
DV/X, it got split between <b><tt>unix-aux.mak</tt></b>,
|
|
|
323 |
<b><tt>unix-end.mak</tt></b>, <b><tt>unixhead.mak</tt></b>,
|
|
|
324 |
<b><tt>unixinst.mak</tt></b>, and <b><tt>unixlink.mak</tt></b>.
|
|
|
325 |
|
|
|
326 |
</ul>
|
|
|
327 |
|
|
|
328 |
<p>
|
|
|
329 |
For MS-DOS and MS Windows builds, there should be:
|
|
|
330 |
|
|
|
331 |
<ul>
|
|
|
332 |
|
|
|
333 |
<li>A makefile for all MS OS (DOS or Windows) builds, for all
|
|
|
334 |
compilers and products.
|
|
|
335 |
|
|
|
336 |
<li>Perhaps a makefile for all MS-DOS builds, for all compilers and
|
|
|
337 |
products, although since Watcom is the only such compiler we're likely to
|
|
|
338 |
support this may be overkill.
|
|
|
339 |
|
|
|
340 |
<li>A makefile for all MS Windows builds, for all compilers and products.
|
|
|
341 |
|
|
|
342 |
<li>A makefile for all Watcom builds (DOS or Windows), for all products.
|
|
|
343 |
|
|
|
344 |
<li>A top-level makefile for the Watcom DOS interpreter product.
|
|
|
345 |
|
|
|
346 |
<li>A top-level makefile for the Watcom Windows interpreter product.
|
|
|
347 |
|
|
|
348 |
<li>A top-level makefile for the Watcom DOS library "product".
|
|
|
349 |
|
|
|
350 |
<li>A top-level makefile for the Watcom Windows library "product".
|
|
|
351 |
|
|
|
352 |
<li>A makefile for all Borland builds (DOS or Windows), for all
|
|
|
353 |
products.
|
|
|
354 |
|
|
|
355 |
</ul>
|
|
|
356 |
|
|
|
357 |
<p>
|
|
|
358 |
and so on.
|
|
|
359 |
|
|
|
360 |
<!-- [2.0 end contents] ==================================================== -->
|
|
|
361 |
|
|
|
362 |
<!-- [3.0 begin visible trailer] =========================================== -->
|
|
|
363 |
<hr>
|
|
|
364 |
|
|
|
365 |
<p>
|
|
|
366 |
<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises. All
|
|
|
367 |
rights reserved.</small>
|
|
|
368 |
|
|
|
369 |
<p>
|
|
|
370 |
This software is provided AS-IS with no warranty, either express or
|
|
|
371 |
implied.
|
|
|
372 |
|
|
|
373 |
This software is distributed under license and may not be copied,
|
|
|
374 |
modified or distributed except as expressly authorized under the terms
|
|
|
375 |
of the license contained in the file LICENSE in this distribution.
|
|
|
376 |
|
|
|
377 |
For more information about licensing, please refer to
|
|
|
378 |
http://www.ghostscript.com/licensing/. For information on
|
|
|
379 |
commercial licensing, go to http://www.artifex.com/licensing/ or
|
|
|
380 |
contact Artifex Software, Inc., 101 Lucas Valley Road #110,
|
|
|
381 |
San Rafael, CA 94903, U.S.A., +1(415)492-9861.
|
|
|
382 |
|
|
|
383 |
<p>
|
|
|
384 |
<small>Ghostscript version 8.53, 20 October 2005
|
|
|
385 |
|
|
|
386 |
<!-- [3.0 end visible trailer] ============================================= -->
|
|
|
387 |
|
|
|
388 |
</body>
|
|
|
389 |
</html>
|