gaf: Fix memory leak

[geda-gaf.git] / docs / gnetlist.1.in

.TH gnetlist 1 "@DATE@" "gEDA Project" @VERSION@
.SH NAME
gnetlist - gEDA/gaf Netlist Extraction and Generation
.SH SYNOPSIS
.B gnetlist
[\fIOPTION\fR...] [\fB-p\fR \fIBACKEND\fR|\fB-g\fR \fIBACKEND\fR] [--] \fIFILE\fR...

.SH DESCRIPTION
.PP

\fBgnetlist\fR is a netlist extraction and generation tool and is part
of the gEDA (GPL Electronic Design Automation) toolset.  It takes one
or multiple electronic schematics as input and outputs a netlist.  A
netlist is a machine-interpretable description of the way that
components in an electronic circuit are connected together and is
commonly used as the input to a PCB layout program such as
\fBpcb\fR(1) or to a simulator such as \fBgnucap\fR(1).

A normal \fBgnetlist\fR run is carried out in two steps.  First, the
\fBgnetlist\fR frontend loads the specified human-readable schematic
\fIFILE\fRs and compiles them to an in-memory netlist description.
Then, a \fIBACKEND\fR is used to export the connection and component
data to one of many supported netlist formats.

\fBgnetlist\fR is extensible in Python and Scheme.

.SH GENERAL OPTIONS
.TP 8
\fB-q\fR
Quiet mode. Turns off all warnings/notes/messages.
.TP 8
\fB-v\fR, \fB--verbose\fR
Verbose mode.  Output all diagnostic information.
.TP 8
\fB-L\fR \fIDIRECTORY\fR
Prepend \fIDIRECTORY\fR to the list of directories to be searched for
Python backends, Scheme backends, and other Scheme files.
.TP 8
\fB-p\fR \fIBACKEND\fR
Specify the Python netlist backend to be used.
.TP 8
\fB-g\fR \fIBACKEND\fR
Specify the Scheme netlist backend to be used.
.TP 8
\fB-O\fR \fISTRING\fR
Pass an option string to the backend.
.TP 8
\fB--list-backends\fR
Print a list of available netlist backends.  A backend name is
prefixed with the letters `P' and `G' in brackets if it is available
as a Python and as a Scheme backend, respectively.
.TP 8
\fB-o\fR \fIFILE\fR
Specify the filename for the generated netlist.  By default, output is
directed to `output.net'.
If `-' is given instead of a filename, the output is directed to the
standard output.
.TP 8
\fB-l\fR \fIFILE\fR
Specify a Scheme file to be loaded before the backend is loaded or
executed.  This option can be specified multiple times.
.TP 8
\fB-m\fR \fIFILE\fR
Specify a Scheme file to be loaded between loading the backend and
executing it.  This option can be specified multiple times.
.TP 8
\fB-c\fR \fIEXPR\fR
Specify a Scheme expression to be executed during \fBgnetlist\fR
startup.  This option can be specified multiple times.
.TP 8
\fB-i\fR
After the schematic files have been loaded and the netlist generated,
enter an interactive Python interpreter.  The netlist structure is
available as `netlist' in the local dictionary.
.TP 8
\fB--report-gui\fR
Report warnings and errors in a GUI dialog.
.TP 8
\fB-h\fR, \fB--help\fR
Print a help message.
.TP 8
\fB-V\fR, \fB--version\fR
Print \fBgnetlist\fR version information.
.TP 8
\fB--\fR
Treat all remaining arguments as schematic filenames.  Use this if you
have a schematic filename which begins with `-'.

.SH BACKENDS
.PP
Currently, \fBgnetlist\fR includes the following backends:

.TP 8
\fBallegro\fR
Allegro netlist format.
.TP 8
\fBbae\fR
Bartels Autoengineer netlist format.
.TP 8
\fBbom\fR, \fBbom2\fR
Bill of materials generation.
.TP 8
\fBcalay\fR
Calay netlist format.
.TP 8
\fBcascade\fR
RF Cascade netlist format.
.TP 8
\fBdrc\fR, \fBdrc2\fR
Design rule checkers (\fBdrc2\fR is recommended).
.TP 8
\fBdumpindent\fR, \fBdumpjson\fR, \fBdumplihata\fR, \fBdumptext\fR, \fBdumpxml\fR
Dump the netlist in various generic formats.
.TP 8
\fBeagle\fR
Eagle netlist format.
.TP 8
\fBewnet\fR
Netlist format for National Instruments ULTIboard layout tool.
.TP 8
\fBfuturenet2\fR
Futurenet2 netlist format.
.TP 8
\fBgeda\fR
Internal gEDA netlist format (used for testing and diagnostics).
.TP 8
\fBgossip\fR
Gossip netlist format.
.TP 8
\fBgsch2pcb\fR
Backend used for \fBpcb\fR(1) file layout generation by
\fBgsch2pcb\fR(1).  It is not recommended to use this backend
directly.
.TP 8
\fBguile\fR
Compatibility layer for old backends written in Scheme.
.TP 8
\fBliquidpcb\fR
LiquidPCB netlist format.
.TP 8
\fBmakedpend\fR
Auto-generate dependencies for Makefiles.
.TP 8
\fBmathematica\fR
Netlister for analytical circuit solving using Mathematica.
.TP 8
\fBmaxascii\fR
MAXASCII netlist format.
.TP 8
\fBosmond\fR
Osmond netlist format.
.TP 8
\fBpads\fR
PADS netlist format.
.TP 8
\fBpartslist1\fR, \fBpartslist2\fR, \fBpartslist3\fR
Bill of materials generation backends (alternatives to \fBbom\fR and
\fBbom2\fR).
.TP 8
\fBPCB\fR
\fBpcb\fR(1) netlist format.
.TP 8
\fBpcbfwd\fR
Internally used by \fBpcb\fR(1)'s "Import Schematics" mechanism.
.TP 8
\fBpcbpins\fR
Generates a \fBpcb\fR(1) action file for forward annotating pin/pad
names from schematic to layout.
.TP 8
\fBprotelII\fR
Protel II netlist format.
.TP 8
\fBredac\fR
RACAL-REDAC netlist format.
.TP 8
\fBspice\fR, \fBspice-sdb\fR, \fBspice-noqsi\fR
SPICE-compatible netlist format (\fBspice-sdb\fR and \fBspice-noqsi\fR
are recommended).
Suitable for use with \fBgnucap\fR(1).
.TP 8
\fBswitcap\fR
SWITCAP switched capacitor simulator netlist format.
.TP 8
\fBsystemc\fR
Structural SystemC code generation.
.TP 8
\fBtango\fR
Tango netlist format.
.TP 8
\fBtedax\fR
tEDAx netlist format (used by \fBpcb-rnd\fR(1)).
.TP 8
\fBvams\fR
VHDL-AMS code generation.
.TP 8
\fBverilog\fR
Verilog code generation.
.TP 8
\fBvhdl\fR
VHDL code generation.
.TP 8
\fBvipec\fR
ViPEC Network Analyser netlist format.


.SH EXAMPLES
.PP
These examples assume that you have a schematic file `stack_1.sch' in
the current directory.
.PP
\fBgnetlist\fR requires that at least one schematic and either a
Python backend, a Scheme backend, or interactive mode are specified on
the command line.  If a backend name is specified with `\-p
\fIBACKEND\fR' (for a Python backend) or `\-g \fIBACKEND\fR' (for a
Scheme backend), \fBgnetlist\fR will output a netlist:

.nf
        gnetlist \-p dumptext stack_1.sch
.ad b

.PP
The netlist output will be written to a file called `output.net'
in the current working directory.

.PP
You can specify the output filename by using the `\-o' option:

.nf
        gnetlist \-p dumptext \-o /tmp/stack.netlist stack_1.sch
.ad b

.PP
Output will now be directed to `/tmp/stack.netlist'.

.PP
You could run (for example) the `spice-sdb' backend against the
schematic if you specified `\-p spice-sdb', or you could generate a
bill of materials for the schematic using `\-p partslist1'.

.PP
To obtain a Python prompt to run Python commands directly, you can
use the `\-i' option.

.nf
        gnetlist \-i stack_1.sch
.ad b

.PP
\fBgnetlist\fR will load `stack_1.sh' and then enter an interactive
Python interpreter.  The netlist structure is available as `netlist'
in the local dictionary.

.SH ENVIRONMENT
.TP 8
.B GEDADATA
specifies the search directory for Scheme and rc files.  The default
is `${prefix}/share/gEDA'.
.TP 8
.B GEDADATARC
specifies the search directory for rc files.  The default is `$GEDADATA'.

.SH AUTHORS
See the `AUTHORS' file included with this program.

.SH COPYRIGHT
.nf
Copyright \(co 1999-@YEAR@ gEDA Contributors.  License GPLv2+: GNU GPL
version 2 or later.  Please see the `COPYING' file included with this
program for full details.
.PP
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

.SH SEE ALSO
\fBgschem\fR(1), \fBgsymcheck\fR(1), \fBpcb\fR(1), \fBpcb-rnd\fR(1), \fBgnucap\fR(1)