gsch2pcb: Make --m4-file and -m4-pcbdir arguments work again.
[geda-gaf/peter-b.git] / gnetlist / docs / gnetlist.1
bloba165f07308ecc4f202e5710bcd658b2701b2a00b
1 .TH gnetlist 1 "June 19th, 2011" "gEDA Project" 1.7.1.20110619
2 .SH NAME
3 gnetlist - gEDA/gaf Netlist Extraction and Generation
4 .SH SYNOPSIS
5 .B gnetlist
6 [\fIOPTION\fR ...] [\fB-g\fR \fIBACKEND\fR] [\fI--\fR] \fIFILE\fR ...
8 .SH DESCRIPTION
9 .PP
11 \fBgnetlist\fR is a netlist extraction and generation tool, and is
12 part of the gEDA (GPL Electronic Design Automation) toolset.  It takes
13 one or electronic schematics as input, and outputs a netlist.  A
14 netlist is a machine-interpretable description of the way that
15 components in an electronic circuit are connected together, and is
16 commonly used as the input to a PCB layout program such as
17 \fBpcb\fR(1) or to a simulator such as \fBgnucap\fR(1).
19 A normal \fBgnetlist\fR run is carried out in two steps.  First, the
20 \fBgnetlist\fR frontend loads the specified human-readable schematic
21 \fIFILE\fRs, and compiles them to an in-memory netlist description.
22 Next, a `backend' is used to export the connection and component data
23 to one of many supported netlist formats.
25 \fBgnetlist\fR is extensible, using the Scheme programming language.
27 .SH GENERAL OPTIONS
28 .TP 8
29 \fB-q\fR
30 Quiet mode. Turns off all warnings/notes/messages.
31 .TP 8
32 \fB-v\fR, \fB--verbose\fR
33 Verbose mode.  Output all diagnostic information.
34 .TP 8
35 \fB-L\fR \fIDIRECTORY\fR
36 Prepend \fIDIRECTORY\fR to the list of directories to be searched for
37 Scheme files.
38 .TP 8
39 \fB-g\fR \fIBACKEND\fR
40 Specify the netlist backend to be used.
41 .TP 8
42 \fB-O\fR \fISTRING\fR
43 Pass an option string to the backend.
44 .TP 8
45 \fB--list-backends\fR
46 Print a list of available netlist backends.
47 .TP 8
48 \fB-o\fR \fIFILE\fR
49 Specify the filename for the generated netlist.  By default, output is
50 directed to `output.net'.
51 .TP 8
52 \fB-l\fR \fIFILE\fR
53 Specify a Scheme file to be loaded before the backend is loaded or
54 executed.  This option can be specified multiple times.
55 .TP 8
56 \fB-m\fR \fIFILE\fR
57 Specify a Scheme file to be loaded between loading the backend and
58 executing it.  This option can be specified multiple times.
59 .TP 8
60 \fB-c\fR \fIEXPR\fR
61 Specify a Scheme expression to be executed during \fBgnetlist\fR
62 startup.  This option can be specified multiple times.
63 .TP 8
64 \fB-i\fR
65 After the schematic files have been loaded and compiled, and after all
66 Scheme files have been loaded, but before running the backend, enter a
67 Scheme read-eval-print loop.
68 .TP 8
69 \fB-h\fR, \fB--help\fR
70 Print a help message.
71 .TP 8
72 \fB-V\fR, \fB--version\fR
73 Print \fBgnetlist\fR version information.
74 .TP 8
75 \fB--\fR
76 Treat all remaining arguments as schematic filenames.  Use this if you
77 have a schematic filename which begins with `-'.
79 .SH BACKENDS
80 .PP
81 Currently, \fBgnetlist\fR includes the following backends:
83 .TP 8
84 \fBallegro\fR
85 Allegro netlist format.
86 .TP 8
87 \fBbae\fR
88 Bartels Autoengineer netlist format.
89 .TP 8
90 \fBbom\fR, \fBbom2\fR
91 Bill of materials generation.
92 .TP 8
93 \fBcalay\fR
94 Calay netlist format.
95 .TP 8
96 \fBcascade\fR
97 RF Cascade netlist format
98 .TP 8
99 \fBdrc\fR, \fBdrc2\fR
100 Design rule checkers (\fBdrc2\fR is recommended).
101 .TP 8
102 \fBeagle\fR
103 Eagle netlist format.
104 .TP 8
105 \fBewnet\fR
106 Netlist format for National Instruments ULTIboard layout tool.
107 .TP 8
108 \fBfuturenet2\fR
109 Futurenet2 netlist format.
110 .TP 8
111 \fBgeda\fR
112 Native gEDA netlist format (mainly used for testing and diagnostics).
113 .TP 8
114 \fBgossip\fR
115 Gossip netlist format.
116 .TP 8
117 \fBgsch2pcb\fR
118 Backend used for \fBpcb\fR(1) file layout generation by
119 \fBgsch2pcb\fR(1).  It is not recommended to use this backend
120 directly.
121 .TP 8
122 \fBliquidpcb\fR
123 LiquidPCB netlist format.
124 .TP 8
125 \fBmathematica\fR
126 Netlister for analytical circuit solving using Mathematica.
127 .TP 8
128 \fBmaxascii\fR
129 MAXASCII netlist format.
130 .TP 8
131 \fBosmond\fR
132 Osmond netlist format.
133 .TP 8
134 \fBpads\fR
135 PADS netlist format.
136 .TP 8
137 \fBpartslist1\fR, \fBpartslist2\fR, \fBpartslist3\fR
138 Bill of materials generation backends (alternatives to \fBbom\fR and
139 \fBbom2\fR).
140 .TP 8
141 \fBPCB\fR
142 \fBpcb\fR(1) netlist format.
143 .TP 8
144 \fBpcbpins\fR
145 Generates a \fBpcb\fR(1) action file for forward annotating pin/pad
146 names from schematic to layout.
147 .TP 8
148 \fBprotelII\fR
149 Protel II netlist format.
150 .TP 8
151 \fBredac\fR
152 RACAL-REDAC netlist format.
153 .TP 8
154 \fBspice\fR, \fBspice-sdb\fR
155 SPICE-compatible netlist format (\fBspice-sdb\fR is recommended).
156 Suitable for use with \fBgnucap\fR(1).
157 .TP 8
158 \fBswitcap\fR
159 SWITCAP switched capacitor simulator netlist format.
160 .TP 8
161 \fBsystemc\fR
162 Structural SystemC code generation.
163 .TP 8
164 \fBtango\fR
165 Tango netlist format.
166 .TP 8
167 \fBvams\fR
168 VHDL-AMS code generation.
169 .TP 8
170 \fBverilog\fR
171 Verilog code generation.
172 .TP 8
173 \fBvhdl\fR
174 VHDL code generation.
175 .TP 8
176 \fBvipec\fR
177 ViPEC Network Analyser netlist format.
180 .SH EXAMPLES
182 These examples assume that you have a `stack_1.sch' in the current directory.
184 \fBgnetlist\fR requires that at least one schematic to be specified on the
185 command line:
188         ./gnetlist stack_1.sch
189 .ad b
192 This is not very useful since it does not direct \fBgnetlist\fR to do
193 anything.
195 Specify a backend name with `\-g' to get \fBgnetlist\fR to output a
196 netlist:
199         ./gnetlist \-g geda stack_1.sch
200 .ad b
203 The netlist output will be written to a file called `output.net'
204 in the current working directory.
207 You can specify the output filename by using the `\-o' option:
210         ./gnetlist \-g geda stack_1.sch \-o /tmp/stack.netlist
211 .ad b
214 Output will now be directed to `/tmp/stack.netlist'.
217 You could run (for example) the `spice-sdb' backend against the
218 schematic if you specified `\-g spice-sdb', or you could generate a
219 bill of materials for the schematic using `\-g partslist1'.
222 To obtain a Scheme prompt to run Scheme expressions directly, you can
223 use the `\-i' option.
226         ./gnetlist \-i stack_1.sch
227 .ad b
230 \fBgnetlist\fR will load `stack_1.sh', and then enter an interactive
231 Scheme read-eval-print loop.
233 .SH ENVIRONMENT
234 .TP 8
235 .B GEDADATA
236 specifies the search directory for Scheme and rc files.  The default
237 is `${prefix}/share/gEDA'.
238 .TP 8
239 .B GEDADATARC
240 specifies the search directory for rc files.  The default is `$GEDADATA'.
242 .SH AUTHORS
243 See the `AUTHORS' file included with this program.
245 .SH COPYRIGHT
247 Copyright \(co 1999-2011 gEDA Contributors.  License GPLv2+: GNU GPL
248 version 2 or later.  Please see the `COPYING' file included with this
249 program for full details.
251 This is free software: you are free to change and redistribute it.
252 There is NO WARRANTY, to the extent permitted by law.
254 .SH SEE ALSO
255 \fBgschem\fR(1), \fBgsymcheck\fR(1), \fBpcb\fR(1), \fBgnucap\fR(1)