docs/wiki/libgeda3.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 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
   4  lang="en" dir="ltr">
   5 <head>
   6   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   7   <title>libgeda3</title>
   8 <meta name="generator" content="DokuWiki Release rc2007-05-24" />
   9 <meta name="robots" content="noindex,nofollow" />
  10 <meta name="date" content="2007-05-24T22:27:27-0400" />
  11 <meta name="keywords" content="libgeda3" />
  12 <link rel="search" type="application/opensearchdescription+xml" href="http://geda.seul.org/wiki/lib/exe/opensearch.php" title="geda Wiki" />
  13 <link rel="start" href="http://geda.seul.org/wiki/" />
  14 <link rel="contents" href="http://geda.seul.org/wiki/libgeda3?do=index" title="Index" />
  15 <link rel="alternate" type="application/rss+xml" title="Recent Changes" href="http://geda.seul.org/wiki/feed.php" />
  16 <link rel="alternate" type="application/rss+xml" title="Current Namespace" href="http://geda.seul.org/wiki/feed.php?mode=list&ns=" />
  17 <link rel="alternate" type="text/html" title="Plain HTML" href="http://geda.seul.org/wiki/_export/xhtml/libgeda3" />
  18 <link rel="alternate" type="text/plain" title="Wiki Markup" href="http://geda.seul.org/wiki/_export/raw/libgeda3" />
  19 <link rel="stylesheet" media="all" type="text/css" href="lib/exe/css" />
  20 <link rel="stylesheet" media="screen" type="text/css" href="lib/exe/001css" />
  21 <link rel="stylesheet" media="print" type="text/css" href="lib/exe/002css" />
  22 </head>
  23 <body>
  24 <div class="dokuwiki export">
  25 <div class="toc">
  26 <div class="tocheader toctoggle" id="toc__header">Table of Contents</div>
  27 <div id="toc__inside">
  28
  29 <ul class="toc">
  30 <li class="level1"><div class="li"><span class="li"><a href="#geda_library_v3_specification" class="toc">gEDA Library v3 Specification</a></span></div>
  31 <ul class="toc">
  32 <li class="level2"><div class="li"><span class="li"><a href="#rationale" class="toc">Rationale</a></span></div></li>
  33 <li class="level2"><div class="li"><span class="li"><a href="#requirements" class="toc">Requirements</a></span></div>
  34 <ul class="toc">
  35 <li class="level3"><div class="li"><span class="li"><a href="#core" class="toc">Core</a></span></div></li>
  36 <li class="level3"><div class="li"><span class="li"><a href="#secondary" class="toc">Secondary</a></span></div></li>
  37 </ul>
  38 </li>
  39 <li class="level2"><div class="li"><span class="li"><a href="#coordinate_system" class="toc">Coordinate System</a></span></div></li>
  40 <li class="level2"><div class="li"><span class="li"><a href="#configuration" class="toc">Configuration</a></span></div></li>
  41 <li class="level2"><div class="li"><span class="li"><a href="#dependencies" class="toc">Dependencies</a></span></div>
  42 <ul class="toc">
  43 <li class="level3"><div class="li"><span class="li"><a href="#glib" class="toc">glib</a></span></div></li>
  44 <li class="level3"><div class="li"><span class="li"><a href="#gobject" class="toc">gobject</a></span></div></li>
  45 </ul>
  46 </li>
  47 <li class="level2"><div class="li"><span class="li"><a href="#references" class="toc">References</a></span></div></li></ul>
  48 </li></ul>
  49 </div>
  50 </div>
  51
  52
  53
  54 <h1><a name="geda_library_v3_specification" id="geda_library_v3_specification">gEDA Library v3 Specification</a></h1>
  55 <div class="level1">
  56
  57 </div>
  58 <!-- SECTION "gEDA Library v3 Specification" [1-45] -->
  59 <h2><a name="rationale" id="rationale">Rationale</a></h2>
  60 <div class="level2">
  61
  62 <p>
  63  The current version (2.x) of the libgeda shared library has a number of defects:
  64 </p>
  65 <ul>
  66 <li class="level1"><div class="li"> Poor separation between public interface and internals, which leads to&hellip;</div>
  67 </li>
  68 <li class="level1"><div class="li"> Frequent changes to the <acronym title="Application Programming Interface">API</acronym></div>
  69 </li>
  70 <li class="level1"><div class="li"> <acronym title="Application Programming Interface">API</acronym> contains large amounts of code specific to application internals </div>
  71 </li>
  72 </ul>
  73
  74 <p>
  75  This page is an attempt to itemise in detail what is required of libgeda, and what the interface to it should look like.  This will enable:
  76 </p>
  77 <ul>
  78 <li class="level1"><div class="li"> More rigorous testing of library functions</div>
  79 </li>
  80 <li class="level1"><div class="li"> Creation of language bindings for libgeda</div>
  81 </li>
  82 <li class="level1"><div class="li"> Easier development of other applications for manipulating schematics</div>
  83 </li>
  84 </ul>
  85
  86 </div>
  87 <!-- SECTION "Rationale" [46-643] -->
  88 <h2><a name="requirements" id="requirements">Requirements</a></h2>
  89 <div class="level2">
  90
  91 </div>
  92 <!-- SECTION "Requirements" [644-669] -->
  93 <h3><a name="core" id="core">Core</a></h3>
  94 <div class="level3">
  95 <ol>
  96 <li class="level1"><div class="li"> Define data structures for representing schematics</div>
  97 </li>
  98 <li class="level1"><div class="li"> Provide methods for creating and manipulating schematics</div>
  99 </li>
 100 <li class="level1"><div class="li"> Provide methods for reading and storing schematics into files and data streams</div>
 101 </li>
 102 <li class="level1"><div class="li"> Provide access to detailed data on errors and exceptions</div>
 103 </li>
 104 <li class="level1"><div class="li"> Provide a simple interface for configuring libgeda’s behaviour</div>
 105 </li>
 106 </ol>
 107
 108 </div>
 109 <!-- SECTION "Core" [670-1013] -->
 110 <h3><a name="secondary" id="secondary">Secondary</a></h3>
 111 <div class="level3">
 112 <ol>
 113 <li class="level1"><div class="li"> Make no assumptions about applications which will use the library</div>
 114 </li>
 115 <li class="level1"><div class="li"> Make no assumptions about the compiler or architecture on which the library is being used</div>
 116 </li>
 117 <li class="level1"><div class="li"> Fully reentrant for thread safety</div>
 118 </li>
 119 <li class="level1"><div class="li"> Minimise number of dependency libraries</div>
 120 </li>
 121 <li class="level1"><div class="li"> Detect and gracefully handle multiple instances accessing the same schematic file</div>
 122 </li>
 123 </ol>
 124
 125 </div>
 126 <!-- SECTION "Secondary" [1014-1367] -->
 127 <h2><a name="coordinate_system" id="coordinate_system">Coordinate System</a></h2>
 128 <div class="level2">
 129
 130 <p>
 131  Because libgeda should “make no assumptions about applications which will use the library,&quot; libgeda should use only “world” coordinates throughout (the same coordinate system as used in the files).  See the <a href="geda_file_format_spec.html" class="wikilink1" title="geda:file_format_spec">file format specification</a>.
 132 </p>
 133
 134 </div>
 135 <!-- SECTION "Coordinate System" [1368-1659] -->
 136 <h2><a name="configuration" id="configuration">Configuration</a></h2>
 137 <div class="level2">
 138
 139 <p>
 140  Currently, libgeda relies on an embedded Scheme interpreter (<a href="http://www.gnu.org/software/guile/" class="urlextern" title="http://www.gnu.org/software/guile/"  rel="nofollow">Guile</a>) for configuring settings such as library search paths.  This has a number of pros and cons:
 141 </p>
 142
 143 <p>
 144 Pros:
 145 </p>
 146 <ul>
 147 <li class="level1"><div class="li"> All applications which access libgeda can automatically use the same settings</div>
 148 </li>
 149 <li class="level1"><div class="li"> Arbitrary Scheme code can be used in the configuration process</div>
 150 </li>
 151 </ul>
 152
 153 <p>
 154  Cons:
 155 </p>
 156 <ul>
 157 <li class="level1"><div class="li"> Large &amp; complex dependency</div>
 158 </li>
 159 <li class="level1"><div class="li"> Doesn’t integrate nicely into applications which use e.g. the GNOME or KDE configuration mechanisms</div>
 160 </li>
 161 <li class="level1"><div class="li"> Substantially complicates the creation of graphical user interfaces for configuring library settings</div>
 162 </li>
 163 <li class="level1"><div class="li"> Problems with Guile backward-compatibility in the past</div>
 164 </li>
 165 </ul>
 166
 167 <p>
 168  It might, therefore, make more sense to provide a complete <acronym title="Application Programming Interface">API</acronym> for configuring libgeda, and rely on the application to handle the storage and loading of the configuration.
 169 </p>
 170
 171 </div>
 172 <!-- SECTION "Configuration" [1660-2523] -->
 173 <h2><a name="dependencies" id="dependencies">Dependencies</a></h2>
 174 <div class="level2">
 175
 176 </div>
 177 <!-- SECTION "Dependencies" [2524-2549] -->
 178 <h3><a name="glib" id="glib">glib</a></h3>
 179 <div class="level3">
 180
 181 <p>
 182  <a href="http://developer.gnome.org/doc/API/glib/" class="urlextern" title="http://developer.gnome.org/doc/API/glib/"  rel="nofollow">glib</a> provides a very large number of useful features that would make writing and maintaining libgeda easier.  These include:
 183 </p>
 184 <ul>
 185 <li class="level1"><div class="li"> Portable definitions of basic types (although <code>intptr.h</code> does this too, and would probably be preferable)</div>
 186 </li>
 187 <li class="level1"><div class="li"> Doubly- and singly-linked lists, and many other data structures</div>
 188 </li>
 189 <li class="level1"><div class="li"> Plugin loading, memory allocation, threading, IO abstraction, &hellip;</div>
 190 </li>
 191 </ul>
 192
 193 <p>
 194  Not having to reinvent the wheel &ndash; and letting a much larger project be responsible for optimising and maintaining these features &ndash; would make the libgeda code smaller and easier to understand and maintain.  libgeda already uses glib to a certain extent, but using it more extensively in future versions of libgeda does not immediately seem to be a bad idea.
 195 </p>
 196
 197 </div>
 198 <!-- SECTION "glib" [2550-3349] -->
 199 <h3><a name="gobject" id="gobject">gobject</a></h3>
 200 <div class="level3">
 201
 202 <p>
 203  <a href="http://developer.gnome.org/doc/API/2.0/gobject/" class="urlextern" title="http://developer.gnome.org/doc/API/2.0/gobject/"  rel="nofollow">gobject</a> is an object-oriented programming system in C. It is used extensively in the GTK+ user interface toolkit.  In addition to class-like structures, it provides a signalling system that allows objects to emit, listen for and respond to events.  It is designed to be compatible with the object systems of other languages, and this is one of the chief reasons that so many bindings of GTK+ are available (Python, <acronym title="Practical Extraction and Report Language">Perl</acronym>, .NET, Java, C++, etc).
 204 </p>
 205
 206 <p>
 207 gobject is often considered to be heavyweight, requiring lots of boilerplate code in order to use it effectively.  Its use in libgeda has historically been opposed, though its use in future versions may ease creation of bindings for libgeda in more directly object-oriented languages such as Python, Java or C++.
 208 </p>
 209
 210 </div>
 211 <!-- SECTION "gobject" [3350-4179] -->
 212 <h2><a name="references" id="references">References</a></h2>
 213 <div class="level2">
 214 <ul>
 215 <li class="level1"><div class="li"> <a href="http://www.unet.univie.ac.at/aix/aixprggd/genprogc/writing_reentrant_thread_safe_code.htm" class="urlextern" title="http://www.unet.univie.ac.at/aix/aixprggd/genprogc/writing_reentrant_thread_safe_code.htm"  rel="nofollow">Writing Reentrant and Thread-Safe Code</a></div>
 216 </li>
 217 </ul>
 218
 219 </div>
 220 <!-- SECTION "References" [4180-] --></div>
 221 </body>
 222 </html>