utils/docs/gsch2pcb.1

   1 .TH gsch2pcb 1 "June 19th, 2011" "gEDA Project" 1.7.1.20110619
   2 .SH NAME
   3 gsch2pcb - Update PCB layouts from gEDA/gaf schematics
   4 .SH SYNOPSIS
   5 \fBgsch2pcb\fR [\fIOPTION\fR ...] {\fIPROJECT\fR | \fIFILE\fR ...}
   6 .SH DESCRIPTION
   7 .PP
   8 \fBgsch2pcb\fR is a frontend to \fBgnetlist\fR(1) which aids in
   9 creating and updating \fBpcb\fR(1) printed circuit board layouts based
  10 on a set of electronic schematics created with \fBgschem\fR(1).
  11
  12 .PP
  13 Instead of specifying all options and input gEDA schematic \fIFILE\fRs
  14 on the command line, \fBgsch2pcb\fR can use a \fIPROJECT\fR file
  15 instead.
  16
  17 .PP
  18 \fBgsch2pcb\fR first runs \fBgnetlist\fR(1) with the `PCB' backend to
  19 create a `<name>.net' file containing a \fBpcb\fR(1) formatted netlist for
  20 the design.
  21
  22 .PP
  23 The second step is to run \fBgnetlist\fR(1) again with the `gsch2pcb'
  24 backend to find any \fBM4\fR(1) elements required by the schematics.
  25 Any missing elements are found by searching a set of file element
  26 directories.  If no `<name>.pcb' file exists for the design yet, it is
  27 created with the required elements; otherwise, any new elements
  28 are output to a `<name>.new.pcb' file.
  29
  30 .PP
  31 If a `<name>.pcb' file exists, it is searched for elements with a
  32 non-empty element name with no matching schematic symbol.  These
  33 elements are removed from the `<name>.pcb' file, with a backup in a
  34 `<name>.pcb.bak' file.
  35
  36 .PP
  37 Finally, \fBgnetlist\fR(1) is run a third time with the `pcbpins'
  38 backend to create a `<name>.cmd' file.  This can be loaded into
  39 \fBpcb\fR(1) to rename all pin names in the PCB layout to match the
  40 schematic.
  41
  42 .SH OPTIONS
  43 .TP 8
  44 \fB-o\fR, \fB--output-name\fR=\fIBASENAME\fR
  45 Use output filenames `\fIBASENAME\fR.net', `\fIBASENAME\fR.pcb', and
  46 `\fIBASENAME\fR.new.pcb'.  By default, the basename of the first
  47 schematic file in the list of input files is used.
  48 .TP 8
  49 \fB-d\fR, \fB--elements-dir\fR=\fIDIRECTORY\fR
  50 Add \fIDIRECTORY\fR to the list of directories to search for PCB file
  51 elements.  By default, the following directories are searched if they
  52 exist: `./packages', `/usr/local/share/pcb/newlib',
  53 `/usr/share/pcb/newlib', `/usr/local/lib/pcb_lib', `/usr/lib/pcb_lib',
  54 `/usr/local/pcb_lib'.
  55 .TP 8
  56 \fB-f\fR, \fB--use-files\fR
  57 Force use of file elements in preference to elements generated with
  58 \fBM4\fR(1).
  59 .TP 8
  60 \fB-s\fR, \fB--skip-m4\fR
  61 Disable element generation using \fBM4\fR(1) entirely.
  62 .TP 8
  63 \fB--m4-file\fR \fIFILE\fR
  64 Use the \fBM4\fR(1) file \fIFILE\fR in addition to the default M4
  65 files `./pcb.inc' and `~/.pcb/pcb.inc'.
  66 .TP 8
  67 \fB--m4-pcbdir\fR \fIDIRECTORY\fR
  68 Set \fIDIRECTORY\fR as the directory where \fBgsch2pcb\fR should look
  69 for \fBM4\fR(1) files installed by \fBpcb\fR(1).
  70 .TP 8
  71 \fB-r\fR, \fB--remove-unfound\fR
  72 Don't include references to unfound elements in the generated `.pcb'
  73 files.  Use if you want \fBpcb\fR(1) to be able to load the
  74 (incomplete) `.pcb' file.  This is enabled by default.
  75 .TP 8
  76 \fB-k\fR, \fB--keep-unfound\fR
  77 Keep include references to unfound elements in the generated `.pcb'
  78 files.  Use if you want to hand edit or otherwise preprocess the
  79 generated `.pcb' file before running \fBpcb\fR(1).
  80 .TP 8
  81 \fB-p\fR, \fB--preserve\fR
  82 Preserve elements in PCB files which are not found in the schematics.
  83 Since elements with an empty element name (schematic "refdes") are
  84 never deleted, this option is rarely useful.
  85 .TP 8
  86 \fB--gnetlist\fR \fIBACKEND\fR
  87 In addition to the default backends, run \fBgnetlist\fR(1) with `-g
  88 \fIBACKEND\fR', with output to `<name>.\fIBACKEND\fR'.
  89 .TP 8
  90 \fB--gnetlist-arg\fR \fIARG\fR
  91 Pass \fIARG\fR as an additional argument to \fBgnetlist\fR(1).
  92 .TP 8
  93 \fB--empty-footprint\fR \fINAME\fR
  94 If \fINAME\fR is not `none', \fBgsch2pcb\fR will not add elements for
  95 components with that name to the PCB file.  Note that if the omitted
  96 components have net connections, they will still appear in the netlist
  97 and \fBpcb\fR(1) will warn that they are missing.
  98 .TP 8
  99 \fB--fix-elements\fR
 100 If a schematic component's `footprint' attribute is not equal to the
 101 `Description' of the corresponding PCB element, update the
 102 `Description' instead of replacing the element.
 103 .TP 8
 104 \fB-q\fR, \fB--quiet\fR
 105 Don't output information on steps to take after running \fBgsch2pcb\fR.
 106 .TP 8
 107 \fB-v\fR, \fB--verbose\fR
 108 Output extra debugging information.  This option can be specified
 109 twice (`-v -v') to obtain additional debugging for file elements.
 110 .TP 8
 111 \fB-h\fR, \fB--help\fR
 112 Print a help message.
 113 .TP 8
 114 \fB-V\fR, \fB--version\fR
 115 Print \fBgsch2pcb\fR version information.
 116
 117 .SH PROJECT FILES
 118 .PP
 119 A \fBgsch2pcb\fR project file is a file (not ending in `.sch')
 120 containing a list of schematics to process and some options.  Any
 121 long-form command line option can appear in the project file with the
 122 leading `--' removed, with the exception of `--gnetlist-arg',
 123 `--fix-elements', `--verbose', and `--version'.  Schematics should be
 124 listed on a line beginning with `schematics'.
 125 .PP
 126 An example project file might look like:
 127
 128 .nf
 129         schematics partA.sch partB.sch
 130         output-name design
 131 .ad b
 132
 133 .SH ENVIRONMENT
 134 .TP 8
 135 .B GNETLIST
 136 specifies the \fBgnetlist\fR(1) program to run.  The default is
 137 `gnetlist'.
 138
 139 .SH AUTHORS
 140 See the `AUTHORS' file included with this program.
 141
 142 .SH COPYRIGHT
 143 .nf
 144 Copyright \(co 1999-2011 gEDA Contributors.  License GPLv2+: GNU GPL
 145 version 2 or later.  Please see the `COPYING' file included with this
 146 program for full details.
 147 .PP
 148 This is free software: you are free to change and redistribute it.
 149 There is NO WARRANTY, to the extent permitted by law.
 150
 151 .SH SEE ALSO
 152 \fBgschem\fR(1), \fBgnetlist\fR(1), \fBpcb\fR(1)