INSTALL

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