docs/wiki/geda-xorn_getting_started.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <h1 class="sectionedit1" id="getting_started_with_xorn">Getting started with Xorn</h1>
  14 <div class="level1">
  15
  16 <p>
  17 1. First, make sure that you have the latest version of gEDA/gaf installed (version 1.10.0 or later).  When invoking the Python interpreter directly from a non-standard prefix, you have to add the correct PYTHONPATH (see below): either the subdirectory <code>built-packages</code> in the build tree, or the appropriate <code>site-packages</code> directory in the installation.
  18 </p>
  19
  20 <p>
  21 2. <em>(no longer applicable)</em>
  22 </p>
  23
  24 </div>
  25 <!-- EDIT1 SECTION "Getting started with Xorn" [1-432] -->
  26 <h2 class="sectionedit2" id="xorn_as_a_command-line_utility">Xorn as a command-line utility</h2>
  27 <div class="level2">
  28
  29 <p>
  30 3a. Invoke the “<code>xorn</code>” executable with the option “<code>--help</code>” to see a list of subcommands:
  31 </p>
  32 <pre class="code">  xorn/src/command/xorn --help</pre>
  33
  34 <p>
  35 (or “<code>src/command/xorn --help</code>” if you downloaded the Xorn tarball, or just “<code>xorn --help</code>” if you installed Xorn to your <code>PATH</code>)
  36 </p>
  37
  38 <p>
  39 3b. Run the subcommand “<code>xorn netlist</code>” with the options “<code>--help</code>” and “<code>--list-backends</code>” to print a list of options and available backends.
  40 </p>
  41 <pre class="code">  xorn/src/command/xorn netlist --help
  42   xorn/src/command/xorn netlist --list-backends</pre>
  43
  44 <p>
  45 3c. Process a schematic with “<code>xorn netlist</code>” (using the “<code>PCB</code>” backend as an example):
  46 </p>
  47 <pre class="code">  xorn/src/command/xorn netlist \
  48     --symbol-library-search=/usr/share/gEDA/sym \
  49     -g PCB some-schematic.sch</pre>
  50
  51 </div>
  52 <!-- EDIT2 SECTION "Xorn as a command-line utility" [433-1221] -->
  53 <h2 class="sectionedit3" id="interacting_with_xorn_in_a_c_program">Interacting with Xorn in a C program</h2>
  54 <div class="level2">
  55
  56 <p>
  57 4. Write a C program using libxornstorage and link it against the library:
  58 </p>
  59 <pre class="code">  $ cat &gt; example.c
  60   #include &lt;stdio.h&gt;
  61   #include &lt;stdlib.h&gt;
  62   #include &lt;string.h&gt;
  63   #include &lt;xornstorage.h&gt;
  64
  65   int main()
  66   {
  67       xorn_revision_t rev;
  68       xorn_object_t net_ob;
  69       struct xornsch_net net_data;
  70       xorn_object_t *objects;
  71       size_t count;
  72
  73       rev = xorn_new_revision(NULL);
  74
  75       memset(&amp;net_data, 0, sizeof net_data);
  76       net_data.pos.x = 0;
  77       net_data.pos.y = 200;
  78       net_data.size.x = 100;
  79       net_data.size.y = 0;
  80       net_data.color = 4;
  81       net_ob = xornsch_add_net(rev, &amp;net_data);
  82
  83       xorn_finalize_revision(rev);
  84
  85       xorn_get_objects(rev, &amp;objects, &amp;count);
  86       printf(&quot;%d object(s) found\n&quot;, count);
  87       free(objects);
  88
  89       xorn_free_revision(rev);
  90       return 0;
  91   }
  92   ^D
  93   $ gcc -I xorn/include -c example.c
  94   $ ./libtool --mode=link gcc -o example \
  95       example.o xorn/src/storage/libxornstorage.la
  96   $ ./example
  97   1 object(s)</pre>
  98
  99 <p>
 100 If you are using a separate build directory, replace “<code>-I xorn/include</code>” with the path to the subdirectory “<code>xorn/include</code>” in the source directory.
 101 </p>
 102
 103 <p>
 104 For more information, see the <a href="http://hedmen.org/xorn/doc/api/html/xornstorage_8h.html" class="urlextern" title="http://hedmen.org/xorn/doc/api/html/xornstorage_8h.html" rel="nofollow">libxornstorage API documentation</a> (<a href="http://hedmen.org/xorn/doc/api/html/storage.html" class="urlextern" title="http://hedmen.org/xorn/doc/api/html/storage.html" rel="nofollow">overview</a>).
 105 </p>
 106
 107 </div>
 108 <!-- EDIT3 SECTION "Interacting with Xorn in a C program" [1222-2685] -->
 109 <h2 class="sectionedit4" id="using_xorn_as_a_library">Using Xorn as a library</h2>
 110 <div class="level2">
 111
 112 <p>
 113 5. Run the Python 2.7 interpreter with the subdirectory “<code>xorn/built-packages</code>” added to the environment variable “<code>PYTHONPATH</code>”.
 114 </p>
 115 <pre class="code">  $ PYTHONPATH=xorn/built-packages python2.7
 116   Python 2.7.9 (default, Mar  1 2015, 18:22:53)
 117   [GCC 4.9.2] on linux2
 118   Type &quot;help&quot;, &quot;copyright&quot;, &quot;credits&quot; or &quot;license&quot; for more information.
 119   &gt;&gt;&gt;</pre>
 120
 121 <p>
 122 Import the module “<code>xorn.storage</code>” and experiment a bit with the <abbr title="Application Programming Interface">API</abbr>.  Here is how to perform the operations equivalent to the C program above:
 123 </p>
 124 <pre class="code">  &gt;&gt;&gt; import xorn.storage
 125   &gt;&gt;&gt; rev = xorn.storage.Revision()
 126   &gt;&gt;&gt; net_data = xorn.storage.Net(
 127           x = 0, y = 200, width = 100, height = 0, color = 4)
 128   &gt;&gt;&gt; net_ob = rev.add_object(net_data)
 129   &gt;&gt;&gt; rev.finalize()
 130   &gt;&gt;&gt; rev.get_objects()
 131   [&lt;xorn.storage.Object object at ...&gt;]</pre>
 132
 133 <p>
 134 Import the module “<code>xorn.geda.read</code>” and load a schematic or symbol file:
 135 </p>
 136 <pre class="code">  &gt;&gt;&gt; import xorn.geda.read
 137   &gt;&gt;&gt; rev = xorn.geda.read.read(
 138           &#039;/usr/share/gEDA/sym/analog/resistor-1.sym&#039;)
 139   &gt;&gt;&gt; for ob in rev.toplevel_objects():
 140   ...     data = ob.data()
 141   ...     if isinstance(data, xorn.storage.Text):
 142   ...         print data.text
 143   ...
 144   device=RESISTOR
 145   refdes=R?
 146   pins=2
 147   class=DISCRETE</pre>
 148
 149 <p>
 150 For more information, see the <abbr title="Application Programming Interface">API</abbr> documentation of <a href="http://hedmen.org/xorn/doc/api/html/namespacexorn_1_1storage.html" class="urlextern" title="http://hedmen.org/xorn/doc/api/html/namespacexorn_1_1storage.html" rel="nofollow">xorn.storage</a> and <a href="http://hedmen.org/xorn/doc/api/html/namespacexorn_1_1geda.html" class="urlextern" title="http://hedmen.org/xorn/doc/api/html/namespacexorn_1_1geda.html" rel="nofollow">xorn.geda</a>.
 151 </p>
 152
 153 <p>
 154 6. Write and execute a Python program which uses the <code>xorn</code> package:
 155 </p>
 156 <pre class="code">  $ cat &gt; print-attributes.py
 157   #!/usr/bin/env python2
 158   import sys
 159   import xorn.storage
 160   import xorn.geda.read
 161
 162   rev = xorn.geda.read.read(sys.argv[1])
 163   for ob in rev.toplevel_objects():
 164       data = ob.data()
 165       if isinstance(data, xorn.storage.Text):
 166           print data.text
 167   ^D
 168   $ chmod +x print-attributes.py
 169   $ PYTHONPATH=xorn/built-packages ./print-attributes.py \
 170       /usr/share/gEDA/sym/analog/resistor-1.sym
 171   device=RESISTOR
 172   refdes=R?
 173   pins=2
 174   class=DISCRETE</pre>
 175
 176 </div>
 177 <!-- EDIT4 SECTION "Using Xorn as a library" [2686-4757] -->
 178 <h2 class="sectionedit5" id="writing_custom_netlist_backends">Writing custom netlist backends</h2>
 179 <div class="level2">
 180
 181 <p>
 182 7. Invoke “<code>xorn netlist</code>” on your schematic as above, but instead of specifying a netlist backend, use the option “<code>-i</code>”:
 183 </p>
 184 <pre class="code">  $ xorn/src/command/xorn netlist \
 185       --symbol-library-search=/usr/share/gEDA/sym \
 186       -i some-schematic.sch
 187   Python 2.7.9 (default, Mar  1 2015, 18:22:53)
 188   [GCC 4.9.2] on linux2
 189   Type &quot;help&quot;, &quot;copyright&quot;, &quot;credits&quot; or &quot;license&quot; for more information.
 190   (InteractiveConsole)
 191   &gt;&gt;&gt;</pre>
 192
 193 <p>
 194 This option causes “<code>xorn netlist</code>” to enter interactive mode.  You are now in an interactive Python interpreter session, just like above, but have the additional global variable “<code>netlist</code>” available which contains the netlist&#039;s contents.
 195 </p>
 196 <pre class="code">  &gt;&gt;&gt; netlist
 197   &lt;xorn.geda.netlist.netlist.Netlist instance at ...&gt;
 198   &gt;&gt;&gt; netlist.nets
 199   [&lt;xorn.geda.netlist.net.Net instance at ...&gt;, ...]
 200   &gt;&gt;&gt; [net.name for net in netlist.nets]
 201   [..., &#039;GND&#039;, ...]
 202   &gt;&gt;&gt; netlist.nets_by_name[&#039;GND&#039;]
 203   &lt;xorn.geda.netlist.net.Net instance at ...&gt;
 204   &gt;&gt;&gt; netlist.nets_by_name[&#039;GND&#039;].name
 205   &#039;GND&#039;
 206   &gt;&gt;&gt; netlist.nets_by_name[&#039;GND&#039;].connections
 207   [&lt;xorn.geda.netlist.package.PackagePin instance at ...&gt;, ...]
 208   &gt;&gt;&gt; netlist.nets_by_name[&#039;GND&#039;].connections[0].package
 209   &lt;xorn.geda.netlist.package.Package instance at ...&gt;
 210   &gt;&gt;&gt; netlist.nets_by_name[&#039;GND&#039;].connections[0].package.refdes
 211   &#039;U100&#039;
 212   &gt;&gt;&gt; netlist.nets_by_name[&#039;GND&#039;].connections[0].number
 213   &#039;7&#039;
 214
 215   &gt;&gt;&gt; netlist.packages
 216   [&lt;xorn.geda.netlist.package.Package instance at ...&gt;]
 217   &gt;&gt;&gt; netlist.packages_by_refdes
 218   {..., &#039;U100&#039;: &lt;xorn.geda.netlist.package.Package instance at ...&gt;, ...}
 219   &gt;&gt;&gt; netlist.packages_by_refdes[&#039;U100&#039;].get_attribute(&#039;device&#039;)
 220   ...
 221   &gt;&gt;&gt; netlist.packages_by_refdes[&#039;U100&#039;].pins
 222   [&lt;xorn.geda.netlist.package.PackagePin instance at ...&gt;, ...]
 223   &gt;&gt;&gt; netlist.packages_by_refdes[&#039;U100&#039;].pins_by_number
 224   {..., &#039;7&#039;: &lt;xorn.geda.netlist.package.PackagePin instance at ...&gt;, ...}
 225   &gt;&gt;&gt; netlist.packages_by_refdes[&#039;U100&#039;].pins_by_number[&#039;7&#039;].net
 226   &lt;xorn.geda.netlist.net.Net instance at ...&gt;
 227   &gt;&gt;&gt; netlist.packages_by_refdes[&#039;U100&#039;].pins_by_number[&#039;7&#039;].net.name
 228   &#039;GND&#039;</pre>
 229
 230 <p>
 231 8. Write a Python module whose name starts with “<code>gnet_</code>” and which contains a function “<code>run(f, netlist)</code>”.  Use this module as a netlist backend:
 232 </p>
 233 <pre class="code">  $ cat &gt; gnet_count.py
 234   def run(f, netlist):
 235       f.write(&quot;%d packages found\n&quot; % len(netlist.packages))
 236       f.write(&quot;%d nets found\n&quot; % len(netlist.nets))
 237   ^D
 238   $ xorn/src/command/xorn netlist \
 239       --symbol-library-search=/usr/share/gEDA/sym \
 240       -L . -g count some-schematic.sch
 241   1 packages found
 242   4 nets found</pre>
 243
 244 </div>
 245 <!-- EDIT5 SECTION "Writing custom netlist backends" [4758-] --></body>
 246 </html>