docs/wiki/geda-pcb_adding_a_core_action.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 <p>
  14 As an exercise let&#039;s do something easy, like adding an action to PCB.
  15 </p>
  16
  17 <p>
  18 Before you start coding take a look at: <a href="geda-pcb_developer_introduction.html#build_system" class="wikilink1" title="geda-pcb_developer_introduction.html">Build system</a>
  19 It is essential that you have a working build system.
  20 </p>
  21
  22 <p>
  23 When working on the source code of PCB then please make use of lots and lots of comments (preferably doxygen style). In trying to understand the code I was very grateful for every piece of comment the developer had written.
  24 </p>
  25
  26 <p>
  27 First make a file called <em><strong>example.c</strong></em> and add:
  28 </p>
  29 <pre class="code c"><span class="coMULTI">/*!
  30  * =====================================================================================
  31  *
  32  *                                      COPYRIGHT
  33  *  Example action implementation for PCB.
  34  *  Copyright (C) 2015 Robert Zeegers
  35  *
  36  *  This program is free software; you can redistribute it and/or
  37  *  modify it under the terms of the GNU General Public License
  38  *  as published by the Free Software Foundation; either version 2
  39  *  of the License, or (at your option) any later version.
  40  *
  41  *  This program is distributed in the hope that it will be useful,
  42  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  43  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  44  *  GNU General Public License for more details.
  45  *
  46  *  You should have received a copy of the GNU General Public License
  47  *  along with this program; if not, write to the Free Software
  48  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  49  *
  50  *  \File:   example.c
  51  *  \Brief:  Example on how to implement a action in the PCB program.
  52  *  \par Description
  53  *   Example action implementation for PCB, interactive printed circuit board design
  54  *  \copyright (C) 2015 Robert Zeegers
  55  *
  56  *  \Version:  1.0
  57  *  Created:  24/07/15
  58  *
  59  *  \Todo:     nothing
  60  *  \Bug:      not that I know of
  61  *
  62  * =====================================================================================
  63  */</span>
  64 &nbsp;
  65 <span class="coMULTI">/* First thing todo is include global.h  */</span>
  66 <span class="coMULTI">/* This will automatically also include const.h and macro.h */</span>
  67 <span class="co2">#include &quot;global.h&quot;</span>
  68 &nbsp;
  69 <span class="coMULTI">/* Second we include hid.h because we want to register our action to the HID */</span>
  70 <span class="co2">#include &quot;hid.h&quot;</span>
  71 &nbsp;
  72 <span class="coMULTI">/* We are going to add an action and therefore we want it to show-up in the PCB manual, */</span>
  73 <span class="coMULTI">/* so we add some documentation comments */</span>
  74 <span class="coMULTI">/* For the documentation style see the &quot;extract-docs&quot; perl script in the doc directory */</span>
  75 &nbsp;
  76 <span class="coMULTI">/* %start-doc actions DoSilly
  77    This function doesn't do anything useful.
  78 &nbsp;
  79    @example
  80    DoSilly()
  81    @end example
  82 &nbsp;
  83    %end-doc */</span>
  84 &nbsp;
  85 <span class="coMULTI">/* All action entry functions must have the same syntax as defined in */</span>
  86 <span class="coMULTI">/* typedef struct HID_Action (hid.h)  */</span>
  87 <span class="kw4">static</span> <span class="kw4">int</span>
  88 ExampleDo <span class="br0">&#40;</span><span class="kw4">int</span> argc<span class="sy0">,</span> <span class="kw4">char</span> <span class="sy0">**</span>argv<span class="sy0">,</span> <span class="kw4">int</span> x<span class="sy0">,</span> <span class="kw4">int</span> y<span class="br0">&#41;</span>
  89 <span class="br0">&#123;</span>
  90     <span class="coMULTI">/* It should do something, so let's do something silly */</span>
  91     <span class="coMULTI">/* Let's write a Dutch songtext to the Message Log window */</span>
  92     <span class="coMULTI">/* The struct HID is defined in hid.h */</span>
  93     <span class="coMULTI">/* and the variable gui is made available there by &quot;extern HID *gui;&quot; */</span>
  94     <span class="coMULTI">/* First we check if we have a gui. */</span>
  95     <span class="kw1">if</span><span class="br0">&#40;</span> <span class="nu0">1</span> <span class="sy0">==</span> gui<span class="sy0">-&gt;</span>gui <span class="br0">&#41;</span>
  96     <span class="br0">&#123;</span>
  97         <span class="coMULTI">/*  if we have one let's write the songtext */</span>
  98         gui<span class="sy0">-&gt;</span><a href="http://www.opengroup.org/onlinepubs/009695399/functions/log.html"><span class="kw3">log</span></a> <span class="br0">&#40;</span>_<span class="br0">&#40;</span><span class="st0">&quot;Iedereen is van de wereld en de wereld is van iedereen!<span class="es1">\n</span>&quot;</span><span class="br0">&#41;</span><span class="br0">&#41;</span><span class="sy0">;</span>
  99     <span class="br0">&#125;</span>
 100 <span class="br0">&#125;</span>
 101 &nbsp;
 102 <span class="coMULTI">/* Now we have to make an action list. */</span>
 103 <span class="coMULTI">/* Here we make the connection between our command &quot;DoSilly()&quot; and */</span>
 104 <span class="coMULTI">/* the actual function which should be executed ExampleDo().*/</span>
 105 <span class="kw4">static</span> HID_Action exampledo_action_list<span class="br0">&#91;</span><span class="br0">&#93;</span> <span class="sy0">=</span> <span class="br0">&#123;</span>
 106   <span class="br0">&#123;</span><span class="st0">&quot;DoSilly&quot;</span><span class="sy0">,</span> <span class="st0">&quot;Example action&quot;</span><span class="sy0">,</span> ExampleDo<span class="sy0">,</span> <span class="st0">&quot;Always provide some help&quot;</span><span class="sy0">,</span> <span class="st0">&quot;DoSilly()&quot;</span><span class="br0">&#125;</span>
 107 <span class="br0">&#125;</span><span class="sy0">;</span>
 108 &nbsp;
 109 <span class="coMULTI">/* Next a macro to register the action in the HID */</span>
 110 <span class="coMULTI">/* Note the missing ; at the end, that's correct ;-) */</span>
 111 REGISTER_ACTIONS <span class="br0">&#40;</span>exampledo_action_list<span class="br0">&#41;</span></pre>
 112
 113 <p>
 114 For an explanation on the <code>REGISTER_ACTION</code> macro see paragraph <a href="geda-pcb_developer_introduction.html#register" class="wikilink1" title="geda-pcb_developer_introduction.html">REGISTER</a>.
 115 </p>
 116
 117 <p>
 118 Next we need to add our file to the build system.<br/>
 119
 120 We do that in the file <em><strong>MakeFile.am</strong></em>.<br/>
 121 Open <em><strong>MakeFile.am</strong></em> and look for the variable <em class="u">PCB_SRCS</em> and add the file <em><strong>example.c</strong></em> there like the others.
 122 </p>
 123
 124 <p>
 125 Clean your build directory by doing:
 126 </p>
 127 <pre class="code">make distclean</pre>
 128
 129 <p>
 130 Then do:
 131 </p>
 132 <pre class="code">./autogen.sh</pre>
 133
 134 <p>
 135 Now our file is in <em><strong>MakeFile.in</strong></em>
 136 </p>
 137
 138 <p>
 139 Next do:
 140 </p>
 141 <pre class="code">./configure
 142 make</pre>
 143
 144 <p>
 145 Run:
 146 </p>
 147 <pre class="code">src/pcb</pre>
 148
 149 <p>
 150 In the PCB program type “:DoSilly()” and watch the message log window.
 151 </p>
 152
 153 <p>
 154 And do check out the pcb manual in doc/pcb.pdf search for “DoSilly”
 155 </p>
 156 </body>
 157 </html>