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 40overview</a> and the documents on <a href="Make.htm">how to build 41Ghostscript</a> from source, <a href="C-style.htm">Ghostscript C coding 42guidelines</a>, <a href="Drivers.htm">drivers</a>, the 43<a href="Lib.htm">Ghostscript library</a> and <a href="Install.htm">how to 44install 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> 57The 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 103interpreter; <b><tt>gserver.c</tt></b> is an alternative main program that 104is a rudimentary server. If you configure Ghostscript as a server rather 105than an interactive program, you will use <b><tt>gserver.c</tt></b> instead 106of <b><tt>gs.c</tt></b>. 107 108<p> 109Files named <b><tt>z</tt></b>*<b><tt>.c</tt></b> are Ghostscript operator 110files. The names of the files generally follow the section headings of the 111operator summary in section 6.2 (Second Edition) or 8.2 (Third Edition) of 112the PostScript Language Reference Manual. Each operator XXX is implemented 113by 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> 117Files named <b><tt>i</tt></b>*<b><tt>.c</tt></b>, and *<b><tt>.h</tt></b> 118other than <b><tt>g</tt></b>*<b><tt>.h</tt></b>, are the rest of the 119interpreter. See the makefile for a little more information on how the 120files are divided functionally. 121 122<p> 123The main loop of the PostScript interpreter is the <b><tt>interp</tt></b> 124procedure in <b><tt>interp.c</tt></b>. When the interpreter is reading 125from 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 130useful for printing PostScript objects when debugging. 131 132<hr> 133 134<h2><a name="PDF_interpreter"></a>PDF interpreter</h2> 135 136<p> 137The PDF interpreter is written entirely in PostScript. Its main loop is 138the <b><tt>.pdfrun</tt></b> procedure in <b><tt>pdf_base.ps</tt></b>. When 139the 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. 141This 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> 148Files 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 150than <b><tt>gs.c</tt></b> and <b><tt>gserver.c</tt></b>, are the 151Ghostscript library. Files beginning with <b><tt>gdev</tt></b> are device 152drivers or related code, also part of the library. Other files beginning 153with <b><tt>g</tt></b> are library files that don't fall neatly into either 154the kernel or the driver category. 155 156<p> 157Files 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, 159including 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> 166The interface between the graphics library and device drivers is the only 167really well documented one in all of Ghostscript: see the 168<a href="Drivers.htm">documentation on drivers</a>. 169 170<p> 171In 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 173drivers 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> 178Drivers are divided into "printer" drivers, which support banding, and 179non-printer drivers, which don't. The decision whether banding is 180required is made (by default on the basis of how much memory is available) 181in the procedure <b><tt>gdev_prn_alloc</tt></b> in 182<b><tt>gdevprn.c</tt></b>: it implements this decision by filling the 183virtual procedure table for the printer device in one of two different 184ways. 185 186<p> 187A 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 189boilerplate. There are no simple non-printer drivers that actually drive 190devices: probably the simplest non-printer driver for reading is 191<b><tt>gdevm8.c</tt></b>, which implements 8-bit-deep devices that only 192store the bits in memory. 193 194<h3><a name="Platform_specific_code"></a>Platform-specific code</h3> 195 196<p> 197There are very few platform dependencies in Ghostscript. Ghostscript deals 198with 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 203that 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 206mechanically-discovered platform properties like byte order, size of 207<b><tt>int</tt></b>, etc. These properties, <b>not</b> the names of 208specific platforms, are used to select between different algorithms or 209parameters at compile time. 210 211<li>Files named <b><tt>gp</tt></b>*<b><tt>.h</tt></b> define interfaces 212that are intended to be implemented differently on each platform, but whose 213specification is common to all platforms. 214</ul> 215 216<p> 217The 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> 271If you are going to extend Ghostscript to new machines or operating 272systems, check the *<b><tt>_.h</tt></b> files for <b><tt>ifdef</tt></b> on 273things other than <b><tt>DEBUG</tt></b>. You should probably plan to make 274a 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> 281This section is only for advanced developers who need to integrate 282Ghostscript into a larger program at build time. 283 284<p> 285NOTE: THIS SECTION IS INCOMPLETE. IT WILL BE IMPROVED IN A LATER REVISION. 286 287<p> 288The Ghostscript makefiles are meant to be organized according to the 289following two principles: 290 291<ul> 292 293<li>All the parameters that vary from platform to platform appear in the 294top-level makefile for a given platform. ("Platform" = OS + compiler + 295choice of interpreter vs. library) 296 297<li>All the rules and definitions that can meaningfully be shared among more 298than 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> 303Thus, 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 314products. 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 321cares about the order of definitions, and because some of it is shared with 322DV/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> 329For 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 337products, although since Watcom is the only such compiler we're likely to 338support 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> 358and 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 367rights reserved.</small> 368 369<p> 370This software is provided AS-IS with no warranty, either express or 371implied. 372 373This software is distributed under license and may not be copied, 374modified or distributed except as expressly authorized under the terms 375of the license contained in the file LICENSE in this distribution. 376 377For more information about licensing, please refer to 378http://www.ghostscript.com/licensing/. For information on 379commercial licensing, go to http://www.artifex.com/licensing/ or 380contact Artifex Software, Inc., 101 Lucas Valley Road #110, 381San 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> 390