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
16printing system. The "cups" library provides all of the common application and
17filter functions while the "cupsimage" library provides all of the imaging
18functions used in raster printer drivers. The "cups" library functions are
19accessed by including the <var>&lt;cups/cups.h&gt;</var> header, while
20"cupsimage" functions are found in the <var>&lt;cups/raster.h&gt;</var>
21header.</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.
26The method of compiling against the libraries varies depending on the
27operating system and installation of CUPS. The following sections show how
28to 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 &lt;stdio.h&gt;
34#include &lt;cups/cups.h&gt;
35
36int main(void)
37{
38  int i;
39  cups_dest_t *dests, *dest;
40  int num_dests = cupsGetDests(&amp;dests);
41
42  for (i = num_dests, dest = dests; i &gt; 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,
57then select the <var>Standard Tool</var> project type under <var>Command Line
58Utility</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
62control-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
64chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
65down 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.
69Replace 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
75favorite editor and then run the following command to compile it with GCC and
76run it:</p>
77
78<pre class="command">
79gcc -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
85local 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>
91guide. Raster printer driver developers should also read the
92<a href="api-raster.html" target="_top">Raster API</a> reference.</p>
93