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