1 <!-- 2 Introduction to CUPS programming content for CUPS. 3 4 Copyright 2008-2011 by Apple Inc. 5 6 These coded instructions, statements, and computer programs are the 7 property of Apple Inc. and are protected by Federal copyright 8 law. Distribution and use rights are outlined in the file "LICENSE.txt" 9 which should have been included with this file. If this file is 10 file is missing or damaged, see the license at "http://www.cups.org/". 11 --> 12 13 <h2 class="title"><a name="OVERVIEW">Overview</a></h2> 14 15 <p>CUPS provides two libraries that interface with the different parts of the 16 printing system. The "cups" library provides all of the common application and 17 filter functions while the "cupsimage" library provides all of the imaging 18 functions used in raster printer drivers. The "cups" library functions are 19 accessed by including the <var><cups/cups.h></var> header, while 20 "cupsimage" functions are found in the <var><cups/raster.h></var> 21 header.</p> 22 23 <h2 class="title"><a name="COMPILING">Compiling Programs</a></h2> 24 25 <p>The CUPS libraries can be used from any C, C++, or Objective C program. 26 The method of compiling against the libraries varies depending on the 27 operating system and installation of CUPS. The following sections show how 28 to compile a simple program (shown below) in two common environments.</p> 29 30 <p>The following simple program lists the available printers on the system:</p> 31 32 <pre class="example"> 33 #include <stdio.h> 34 #include <cups/cups.h> 35 36 int main(void) 37 { 38 int i; 39 cups_dest_t *dests, *dest; 40 int num_dests = cupsGetDests(&dests); 41 42 for (i = num_dests, dest = dests; i > 0; i --, dest ++) 43 { 44 if (dest->instance) 45 printf("%s/%s\n", dest->name, dest->instance); 46 else 47 puts(dest->name); 48 } 49 50 return (0); 51 } 52 </pre> 53 54 <h3><a name="XCODE">Compiling with Xcode</a></h3> 55 56 <p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu, 57 then select the <var>Standard Tool</var> project type under <var>Command Line 58 Utility</var>. Click <var>Next</var> and choose a project directory. Click 59 <var>Next</var> to create the project.</p> 60 61 <p>In the project window, double-click on the <var>Targets</var> group and 62 control-click on the simple target to show the context menu. Choose 63 <var>Existing Framework...</var> from the <var>Add</var> submenu. When the file 64 chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll 65 down the file list and select the <var>libcups.dylib</var> file. Click the 66 <var>Add</var> button in the file chooser and attributes sheets.</p> 67 68 <p>In the project window, double-click on the <var>main.c</var> source file. 69 Replace the template source code with the listing above and save it. Click the 70 <var>Build and Go</var> button to build the sample program and run it.</p> 71 72 <h3><a name="COMMANDLINE">Compiling with GCC</a></h3> 73 74 <p>From the command-line, create a file called <var>sample.c</var> using your 75 favorite editor and then run the following command to compile it with GCC and 76 run it:</p> 77 78 <pre class="command"> 79 gcc -o simple `cups-config --cflags` simple.c `cups-config --libs` 80 ./simple 81 </pre> 82 83 <p>The <code>cups-config</code> command provides the compiler flags 84 ("cups-config --cflags") and libraries ("cups-config --libs") needed for the 85 local system.</p> 86 87 <h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2> 88 89 <p>If you are developing a print filter, driver, or backend, see the 90 <a href="api-filter.html" target="_top">Filter and Backend Programming</a> 91 guide. Raster printer driver developers should also read the 92 <a href="api-raster.html" target="_top">Raster API</a> reference.</p> 93