INSTALL

   1 PCB uses a standard GNU autoconf/automake based build
   2 system which should make compilation go smoothly on most unix-like
   3 systems.  Please do read this first section however.
   4
   5 PCB is organized into a core program that deals with all of the
   6 internal database procedures and a collection of Human Interface
   7 Devices (HID's).  The HID's provide exporting/printing capability
   8 as well as a graphical user interface.  At the time of writing
   9 this document PCB includes the following HIDs:
  10
  11 GUI HID's:
  12      gtk      -- GTK based GUI.  This is the default GUI.  You will
  13                  need gtk-2.4 or newer installed (both the runtime
  14                  files as well as the developer headers).  You only
  15                  need gtk if you want the gtk HID.
  16
  17      lesstif  -- motif/lesstif based GUI.  To use the lesstif HID
  18                  you will need Motif, OpenMotif, or Lesstif installed.
  19                  Again you need both libraries and headers.
  20
  21      The choice of which gui to use (if you want something other than
  22      the default of GTK) is indicated with the --with-gui configure
  23      option.  Examples are:
  24        --with-gui=lesstif  = picks the lesstif HID
  25        --with-gui=gtk      = picks the GTK HID
  26        --without-gui       = specifies that no GUI will be built.  This
  27                              option is primarily intended for use in a
  28                              web server environment where you may wish
  29                              to export .pcb files to graphical files on
  30                              the fly but you do not want to install
  31                              X11 or any GUI tooliks on the server.
  32
  33 Export HID's:
  34      ps       -- Postscript and Encapsulated Postscript output.  No
  35                  additional libraries are needed for this.
  36
  37      gcode    -- CNC G-CODE output (experimental).  The gdlib library
  38                  is used by this HID.  gdlib may be found at
  39                  http://www.libgd.org
  40
  41      gerber   -- RS-274-X (Gerber) and Excellon drill output.  No
  42                  additional libraries are needed for this.
  43
  44      bom      -- Bill of materials (BOM) and Centroid (X-Y) output.
  45                  No additional libraries are needed for this.
  46
  47      png      -- png/gif/jpeg output.  This HID uses gdlib to do
  48                  the majority of the work.  gdlib may be obtained
  49                  from http://www.libgd.org.  At the time of
  50                  writing this document, I have tested with
  51                  gd-2.0.23 and gd-2.0.33.  Other versions may
  52                  work as well.
  53
  54                  Since some installations of gdlib may not support
  55                  all three of the formats mentioned here (png, gif,
  56                  and jpeg), PCB provides configure options to individually
  57                  turn off each of these output formats.  These options
  58                  are:
  59                    --disable-gif, --disable-jpeg, and --disable-png
  60                  By having you, the user, explicitly turn off the different
  61                  formats hopefully it will avoid suprises when the
  62                  disabled formats are not available at runtime.
  63
  64     The choice of which export HID's to compile is indicated with:
  65
  66       --with-exporters="ps gerber bom png"
  67
  68     By default all available exporters will be configured in if --with-exporters
  69     is not given.
  70
  71 Printer HID's:
  72      lpr     -- Unix line printer support.  No additional libraries are
  73                 needed for this.
  74
  75      The choice of which printer HID's to compile is indicated with:
  76
  77        --with-printers="lpr"
  78
  79      By default all available printers will be configured in if --with-printers
  80      is not given.
  81
  82 In addition to the libraries listed above, there is a graphical QFP footprint
  83 creator which uses TCL/TK.  If you do not wish to use this feature, and you
  84 do not have TCL/TK installed on your system, you may simply set WISH to
  85 /usr/bin/true in your configure environment.  For example:
  86
  87   env WISH=/usr/bin/true ./configure
  88
  89
  90 Please refer to the output of
  91
  92   ./configure --help
  93
  94 for the most up to date details on the options.
  95
  96 After running ./configure with your selected options, run
  97
  98   make
  99
 100 to build PCB.  You can try out the program by running
 101
 102   cd src
 103   ./pcbtest.sh
 104
 105 prior to installation.
 106
 107 To install PCB after it has been built run:
 108
 109   make install
 110
 111 from the top level directory.
 112
 113 -------- Summary of dependencies --------------------
 114
 115 - GNU m4.  In particular your m4 must support -F for frozen files.
 116
 117 - wish (part of tcl/tk).  If not installed, set WISH=/bin/false in
 118   your configure environment and you just won't get the graphical
 119   QFP footprint builder
 120
 121 - gtk if you are using the gtk frontend
 122
 123 - motif or lesstif if you are using the lesstif frontend
 124
 125 - gdlib if you are using the png HID
 126
 127 - GNU make for building
 128
 129 - flex
 130
 131 - bison
 132
 133 -------- Standard GNU INSTALL Instructions Follow --------------------
 134
 135 This is a generic INSTALL file for utilities distributions.
 136 If this package does not come with, e.g., installable documentation or
 137 data files, please ignore the references to them below.
 138
 139 To compile this package:
 140
 141 1.  Configure the package for your system.  In the directory that this
 142 file is in, type `./configure'.  If you're using `csh' on an old
 143 version of System V, you might need to type `sh configure' instead to
 144 prevent `csh' from trying to execute `configure' itself.
 145
 146 The `configure' shell script attempts to guess correct values for
 147 various system-dependent variables used during compilation, and
 148 creates the Makefile(s) (one in each subdirectory of the source
 149 directory).  In some packages it creates a C header file containing
 150 system-dependent definitions.  It also creates a file `config.status'
 151 that you can run in the future to recreate the current configuration.
 152
 153 Running `configure' takes a minute or two.  While it is running, it
 154 prints some messages that tell what it is doing.  If you don't want to
 155 see the messages, run `configure' with its standard output redirected
 156 to `/dev/null'; for example, `./configure >/dev/null'.
 157
 158 To compile the package in a different directory from the one
 159 containing the source code, you must use a version of `make' that
 160 supports the VPATH variable, such as GNU `make'.  `cd' to the directory
 161 where you want the object files and executables to go and run
 162 `configure'.  `configure' automatically checks for the source code in
 163 the directory that `configure' is in and in `..'.  If for some reason
 164 `configure' is not in the source code directory that you are
 165 configuring, then it will report that it can't find the source code.
 166 In that case, run `configure' with the option `--srcdir=DIR', where
 167 DIR is the directory that contains the source code.
 168
 169 By default, `make install' will install the package's files in
 170 /usr/local/bin, /usr/local/lib, /usr/local/man, etc.  You can specify an
 171 installation prefix other than /usr/local by giving `configure' the option
 172 `--prefix=PATH'.  Alternately, you can do so by consistently giving a value
 173 for the `prefix' variable when you run `make', e.g.,
 174         make prefix=/usr/gnu
 175         make prefix=/usr/gnu install
 176
 177 You can specify separate installation prefixes for
 178 architecture-specific files and architecture-independent files.  If
 179 you give `configure' the option `--exec-prefix=PATH' or set the
 180 `make' variable `exec_prefix' to PATH, the package will use PATH as
 181 the prefix for installing programs and libraries.  Data files and
 182 documentation will still use the regular prefix.  Normally, all files
 183 are installed using the regular prefix.
 184
 185 Another `configure' option is useful mainly in `Makefile' rules for
 186 updating `config.status' and `Makefile'.  The `--no-create' option
 187 figures out the configuration for your system and records it in
 188 `config.status', without actually configuring the package (creating
 189 `Makefile's and perhaps a configuration header file).  Later, you can
 190 run `./config.status' to actually configure the package.  You can also
 191 give `config.status' the `--recheck' option, which makes it re-run
 192 `configure' with the same arguments you used before.  This option is
 193 useful if you change `configure'.
 194
 195 Some packages pay attention to `--with-PACKAGE' options to `configure',
 196 where PACKAGE is something like `gnu-libc' or `x' (for the X Window System).
 197 The README should mention any --with- options that the package recognizes.
 198
 199 `configure' ignores any other arguments that you give it.
 200
 201 If your system requires unusual options for compilation or linking
 202 that `configure' doesn't know about, you can give `configure' initial
 203 values for some variables by setting them in the environment.  In
 204 Bourne-compatible shells, you can do that on the command line like
 205 this:
 206         CC='gcc -traditional' DEFS=-D_POSIX_SOURCE ./configure
 207
 208 The `make' variables that you might want to override with environment
 209 variables when running `configure' are:
 210
 211 (For these variables, any value given in the environment overrides the
 212 value that `configure' would choose:)
 213 CC              C compiler program.
 214                 Default is `cc', or `gcc' if `gcc' is in your PATH.
 215 INSTALL         Program to use to install files.
 216                 Default is `install' if you have it, `cp' otherwise.
 217
 218 (For these variables, any value given in the environment is added to
 219 the value that `configure' chooses:)
 220 DEFS            Configuration options, in the form `-Dfoo -Dbar ...'
 221                 Do not use this variable in packages that create a
 222                 configuration header file.
 223 LIBS            Libraries to link with, in the form `-lfoo -lbar ...'
 224
 225 If you need to do unusual things to compile the package, we encourage
 226 you to figure out how `configure' could check whether to do them, and
 227 mail diffs or instructions to the address given in the README so we
 228 can include them in the next release.
 229
 230 2.  Type `make' to compile the package.  If you want, you can override
 231 the `make' variables CFLAGS and LDFLAGS like this:
 232
 233         make CFLAGS=-O2 LDFLAGS=-s
 234
 235 3.  If the package comes with self-tests and you want to run them,
 236 type `make check'.  If you're not sure whether there are any, try it;
 237 if `make' responds with something like
 238         make: *** No way to make target `check'.  Stop.
 239 then the package does not come with self-tests.
 240
 241 4.  Type `make install' to install programs, data files, and
 242 documentation.
 243
 244 5.  You can remove the program binaries and object files from the
 245 source directory by typing `make clean'.  To also remove the
 246 Makefile(s), the header file containing system-dependent definitions
 247 (if the package uses one), and `config.status' (all the files that
 248 `configure' created), type `make distclean'.
 249
 250 The file `configure.in' is used as a template to create `configure' by
 251 a program called `autoconf'.  You will only need it if you want to
 252 regenerate `configure' using a newer version of `autoconf'.