README

   1 ==============================================
   2  'gschem and Friends' Electronic Design Suite
   3 ==============================================
   4
   5 Copyright (C) 1998-2019 gEDA Developers
   6
   7 Introduction
   8 ============
   9
  10 The GPL Electronic Design Automation (gEDA) project has produced and
  11 continues working on a full GPL'd suite and toolkit of Electronic
  12 Design Automation tools. These tools are used for electrical circuit
  13 design, schematic capture, simulation, prototyping, and
  14 production. Currently, the gEDA project offers a mature suite of free
  15 software applications for electronics design, including schematic
  16 capture, attribute management, bill of materials (BOM) generation,
  17 netlisting into over 20 netlist formats, analog and digital
  18 simulation, and printed circuit board (PCB) layout.
  19
  20 The gEDA project was started because of the lack of free EDA tools for
  21 POSIX systems with the primary purpose of advancing the state of free
  22 hardware or open source hardware. The suite is mainly being developed
  23 on the GNU/Linux platform with some development effort going into
  24 making sure the tools run on other platforms as well.
  25
  26 The gEDA/gaf suite (this package) provides schematic capture,
  27 netlisting, bill of materials generation, and many other features.
  28
  29 Tools in the gEDA suite
  30 =======================
  31
  32 The major components of the gEDA suite are:
  33
  34 `libgeda'
  35   A library of functions for manipulating gEDA schematics and symbols.
  36
  37 `gschem'
  38   A schematic editor.
  39
  40 `gattrib'
  41   A spreadsheet-like program for bulk editing of component attributes.
  42
  43 `gnetlist'
  44   A highly-flexible, hierarchy-aware utility which parses schematics
  45   to generate a number of outputs, including netlists for a wide
  46   variety of PCB layout tools.  It can also generate bills of
  47   materials and DRC reports for your schematics.
  48
  49 `gsch2pcb'
  50   A command-line utility for streamlining the workflow where `PCB'
  51   <http://pcb.geda-project.org/> and `gschem' are used together.
  52
  53 `gsymcheck'
  54   A utility for checking for common errors in schematic symbol files.
  55
  56 `gaf'
  57   A utility for interactive and batch mode working with gEDA Scheme
  58   API, exporting schematics into various formats, and
  59   configuring all the programs of the suite.
  60
  61 `xorn'
  62   A commmand-line utility working with the new Python API which
  63   converts gEDA files between formats and extracts embedded symbols
  64   and pixmaps from a schematic.
  65
  66 Installation
  67 ============
  68
  69 The information in this section is intended to supplement the
  70 information in the `INSTALL' file.
  71
  72 Dependencies
  73 ------------
  74
  75 In order to compile gEDA from the distributed source archives, you
  76 *must* have the following tools and libraries installed:
  77
  78  - A C/C++ compiler and standard library (GCC/glibc are recommended).
  79
  80  - The `pkg-config' tool for managing shared libraries.
  81    <http://pkgconfig.freedesktop.org/>
  82
  83  - Guile ("GNU's Ubiquitous Intelligent Language for Extensions"),
  84    version 2.0.0 or later.  <http://www.gnu.org/software/guile/>
  85
  86  - GTK+ (the Gimp Toolkit), version 2.18.0 or later.
  87    <http://www.gtk.org/>
  88
  89  - GNU `gettext', version 0.18 or newer.
  90    <http://www.gnu.org/software/gettext/>
  91
  92  - The `lex' tool for generating lexical scanners.  The `flex'
  93    implementation recommended.  <http://flex.sourceforge.net/>
  94
  95  - The `awk' tool for data processing.  GNU Awk (`gawk') is
  96    recommended.  <http://www.gnu.org/software/gawk/>
  97
  98  - The CPython interpreter, version 2.7, including the development
  99    headers.  <https://www.python.org/downloads/>
 100
 101 The following tools and libraries are *highly recommended*:
 102
 103  - GNU `troff' (`groff'). <http://www.gnu.org/software/groff/>
 104
 105  - The freedesktop.org MIME info database.
 106    <http://freedesktop.org/Software/shared-mime-info>
 107
 108  - The freedesktop.org utilities for manipulating .desktop files.
 109    <http://www.freedesktop.org/software/desktop-file-utils>
 110
 111  - The FAM or Gamin daemon and corresponding `libfam' or `libgamin'
 112    client library (Gamin is recommended).  If this is available,
 113    gschem will detect if files have been changed on disk by another
 114    application.  <https://people.gnome.org/~veillard/gamin/>
 115
 116 The following tools and libraries are optional:
 117
 118  - The `doxygen' API documentation tool.  This is required for
 119    building the gEDA developer API documentation, not for the regular
 120    user documentation.  <http://www.stack.nl/~dimitri/doxygen/>
 121
 122  - `Inkscape' or `ImageMagic' for svg to png or pdf conversion
 123    This is required for building the gEDA developer API documentation,
 124    not for the regular user documentation.
 125    <http://inkscape.org/>
 126    <http://www.imagemagick.org/script/index.php>
 127
 128  - `Graphviz' for drawing directed graphs.
 129    This is required for building the gEDA developer API documentation,
 130    not for the regular user documentation.
 131    <http://www.graphviz.org/>
 132
 133 Troubleshooting dependencies
 134 ----------------------------
 135
 136   "I've installed the `libfoo' library, but `./configure' isn't
 137   picking it up!"
 138
 139 Many modern operating system distributions split a library into two
 140 packages:
 141
 142 1. a `libfoo' package, which contains the files necessary to
 143    *run* programs which use `libfoo'.
 144
 145 2. a `libfoo-dev' or `libfoo-devel' package, which contains the files
 146    necessary to *compile* programs which use `libfoo'.
 147
 148 If you're having problems, make sure that you have all of the
 149 necessary `dev' or `devel' packages installed.
 150
 151 Installation from a source archive
 152 ----------------------------------
 153
 154 First extract the archive to a sensible place:
 155
 156   tar -xzvf gEDA-gaf-<version>.tar.gz && cd gEDA-gaf-<version>
 157
 158 Run the configuration script.  You'll probably want to specify silent
 159 rules and a custom directory to install gEDA to, for example:
 160
 161   ./configure --prefix=$HOME/geda --enable-silent-rules
 162
 163 You can then compile gEDA:
 164
 165   make
 166
 167 And install it (if you used a `--prefix' outside your $HOME directory,
 168 you may need to run this as root):
 169
 170   make install
 171
 172 For more information on installing gEDA, see the `INSTALL' document.
 173
 174 Installation from the git repository
 175 ------------------------------------
 176
 177 gEDA uses the `git' version control system.  If you wish to try out
 178 the very latest version of gEDA, you will need to install some extra
 179 tools *in addition to* the ones listed above:
 180
 181   - The `git' version control tool, version 1.6 or newer.
 182     <http://git-scm.com/>
 183
 184   - GNU Automake, version 1.11.0 or newer.
 185     <http://www.gnu.org/software/automake/>
 186
 187   - GNU Autoconf, version 2.60 or newer.
 188     <http://www.gnu.org/software/autoconf/>
 189
 190   - GNU Libtool.  <http://www.gnu.org/software/libtool/>
 191
 192   - GNU Texinfo documentation system.
 193     <http://www.gnu.org/software/texinfo/>
 194
 195     Note that on some distributions the TeX support for Texinfo is
 196     packaged separately.
 197
 198 Once you have these installed, you need to clone the gEDA `git'
 199 repository:
 200
 201   git clone git://git.geda-project.org/geda-gaf.git
 202
 203 To generate the configure script, run:
 204
 205   ./autogen.sh
 206
 207 You can then procede to configure and build gEDA as described above.
 208 For more information on working with the gEDA `git' repository, see
 209 <http://wiki.geda-project.org/geda:scm>.
 210
 211 Building gEDA developer API documentation
 212 =========================================
 213
 214 Several of the gEDA libraries and applications have doxygen API
 215 documentation available.  To generate the API documentation from the
 216 source code, install doxygen (see `Dependencies' above).  Next, add
 217 `--enable-doxygen' to your configure command line, i.e.:
 218
 219   ./configure --enable-doxygen
 220
 221 To compile the documentation (quite a slow process), run:
 222
 223   make doxygen
 224
 225 The documentation can then be found in:
 226
 227   */docs/html/index.html
 228
 229 The PDF version of the documentation isn't generated by default.
 230 If you want it, you have to build it explicitly, e.g.:
 231
 232   cd $(srcdir)/libgeda/docs/latex && make
 233
 234 Getting help
 235 ============
 236
 237 There are several ways to get help with installing and using gEDA:
 238
 239  - The gEDA website <http://www.geda-project.org> has more extensive
 240    information on the gEDA tools, and links to some successful
 241    projects which use gEDA.
 242
 243  - The gEDA documentation wiki contains a large amount of helpful
 244    information.  A static copy is included with this distribution; see
 245    the `docs/wiki/index.html' file.  The wiki is accessible online at
 246    <http://wiki.geda-project.org/>.
 247
 248  - If the resources above didn't help you resolve your problem, or you
 249    are having a *design* problem that you want to get help with,
 250    consider subscribing to and posting your question to the
 251    `geda-user' mailing list.
 252    <http://wiki.geda-project.org/geda:mailinglists>
 253
 254  - Alternatively, you can add your question to the gEDA Answers page
 255    on Launchpad. <https://answers.launchpad.net/geda>
 256
 257  - If you have discovered a bug, have a feature request, or have
 258    written a patch to gEDA, please create an item on the gEDA Bugs
 259    page on Launchpad. <http://bugs.launchpad.net/geda>
 260
 261 License
 262 =======
 263
 264 gEDA/gaf (this package) is freely distributable under the GNU Public
 265 License (GPL) version 2.0 or (at your option) any later version.  See
 266 the `COPYING' file for the full text of the license.
 267
 268 The programs and associated files are:
 269
 270   Copyright (C) 1998-2013 by Ales Hvezda and the respective original
 271   authors.
 272
 273 See the `AUTHORS' file for a more extensive list of contributors to
 274 gEDA.
 275
 276 ..
 277    Local Variables:
 278    mode: text
 279    End: