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