NAME

       gsch2pcb - Update PCB layouts from gEDA/gaf schematics

SYNOPSIS

       gsch2pcb [OPTION ...] {PROJECT | FILE ...}

DESCRIPTION

       gsch2pcb  is  a frontend to gnetlist(1) which aids in creating and updating pcb(1) printed
       circuit board layouts based on a set of electronic schematics created with gschem(1).

       Instead of specifying all options and input gEDA schematic  FILEs  on  the  command  line,
       gsch2pcb can use a PROJECT file instead.

       gsch2pcb  first  runs  gnetlist(1)  with  the  `PCB' backend to create a `<name>.net' file
       containing a pcb(1) formatted netlist for the design.

       The second step is to run gnetlist(1) again with the `gsch2pcb' backend to find any  M4(1)
       elements required by the schematics.  Any missing elements are found by searching a set of
       file element directories.  If no `<name>.pcb' file  exists  for  the  design  yet,  it  is
       created  with  the  required  elements;  otherwise,  any  new  elements  are  output  to a
       `<name>.new.pcb' file.

       If a `<name>.pcb' file exists, it is searched for elements with a non-empty  element  name
       with no matching schematic symbol.  These elements are removed from the `<name>.pcb' file,
       with a backup in a `<name>.pcb.bak' file.

       Finally, gnetlist(1) is  run  a  third  time  with  the  `pcbpins'  backend  to  create  a
       `<name>.cmd'  file.   This  can  be  loaded into pcb(1) to rename all pin names in the PCB
       layout to match the schematic.

OPTIONS

       -o, --output-name=BASENAME
               Use output filenames `BASENAME.net', `BASENAME.pcb', and  `BASENAME.new.pcb'.   By
               default,  the  basename  of the first schematic file in the list of input files is
               used.

       -d, --elements-dir=DIRECTORY
               Add DIRECTORY to the list of directories to search  for  PCB  file  elements.   By
               default,  the  following  directories  are  searched  if they exist: `./packages',
               `/usr/local/share/pcb/newlib', `/usr/share/pcb/newlib',  `/usr/local/lib/pcb_lib',
               `/usr/lib/pcb_lib', `/usr/local/pcb_lib'.

       -f, --use-files
               Force use of file elements in preference to elements generated with M4(1).

       -s, --skip-m4
               Disable element generation using M4(1) entirely.

       --m4-file FILE
               Use  the  M4(1)  file  FILE  in  addition  to the default M4 files `./pcb.inc' and
               `~/.pcb/pcb.inc'.

       --m4-pcbdir DIRECTORY
               Set DIRECTORY as  the  directory  where  gsch2pcb  should  look  for  M4(1)  files
               installed by pcb(1).

       -r, --remove-unfound
               Don't  include  references to unfound elements in the generated `.pcb' files.  Use
               if you want pcb(1) to be able to load  the  (incomplete)  `.pcb'  file.   This  is
               enabled by default.

       -k, --keep-unfound
               Keep include references to unfound elements in the generated `.pcb' files.  Use if
               you want to hand edit or otherwise preprocess the  generated  `.pcb'  file  before
               running pcb(1).

       -p, --preserve
               Preserve  elements  in  PCB  files  which  are not found in the schematics.  Since
               elements with an empty element name (schematic "refdes") are never  deleted,  this
               option is rarely useful.

       --gnetlist BACKEND
               In  addition  to  the  default  backends,  run gnetlist(1) with `-g BACKEND', with
               output to `<name>.BACKEND'.

       --gnetlist-arg ARG
               Pass ARG as an additional argument to gnetlist(1).

       --empty-footprint NAME
               If NAME is not `none', gsch2pcb will not add elements  for  components  with  that
               name  to  the PCB file.  Note that if the omitted components have net connections,
               they will still appear in the netlist and pcb(1) will warn that they are missing.

       --fix-elements
               If a schematic component's `footprint' attribute is not equal to the `Description'
               of  the  corresponding  PCB element, update the `Description' instead of replacing
               the element.

       -q, --quiet
               Don't output information on steps to take after running gsch2pcb.

       -v, --verbose
               Output extra debugging information.  This option can be specified twice (`-v  -v')
               to obtain additional debugging for file elements.

       -h, --help
               Print a help message.

       -V, --version
               Print gsch2pcb version information.

PROJECT FILES

       A  gsch2pcb  project file is a file (not ending in `.sch') containing a list of schematics
       to process and some options.  Any long-form command line option can appear in the  project
       file  with  the  leading  `--'  removed,  with  the exception of `--gnetlist-arg', `--fix-
       elements', `--verbose', and `--version'.  Schematics should be listed on a line  beginning
       with `schematics'.

       An example project file might look like:

            schematics partA.sch partB.sch
            output-name design

ENVIRONMENT

       GNETLIST
               specifies the gnetlist(1) program to run.  The default is `gnetlist'.

AUTHORS

       See the `AUTHORS' file included with this program.

COPYRIGHT

       Copyright © 1999-2011 gEDA Contributors.  License GPLv2+: GNU GPL
       version 2 or later.  Please see the `COPYING' file included with this
       program for full details.

       This is free software: you are free to change and redistribute it.
       There is NO WARRANTY, to the extent permitted by law.

SEE ALSO

       gschem(1), gnetlist(1), pcb(1)