README

   1 ==============================================
   2  'gschem and Friends' Electronic Design Suite
   3 ==============================================
   4
   5 Copyright (C) 1998-2015 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 Installation
  62 ============
  63
  64 The information in this section is intended to supplement the
  65 information in the `INSTALL' file.
  66
  67 Dependencies
  68 ------------
  69
  70 In order to compile gEDA from the distributed source archives, you
  71 *must* have the following tools and libraries installed:
  72
  73  - A C/C++ compiler and standard library (GCC/glibc are recommended).
  74
  75  - The `pkg-config' tool for managing shared libraries.
  76    <http://pkgconfig.freedesktop.org/>
  77
  78  - Guile ("GNU's Ubiquitous Intelligent Language for Extensions"),
  79    version 2.0.0 or later.  <http://www.gnu.org/software/guile/>
  80
  81  - GTK+ (the Gimp Toolkit), version 2.18.0 or later.
  82    <http://www.gtk.org/>
  83
  84  - GNU `gettext', version 0.18 or newer.
  85    <http://www.gnu.org/software/gettext/>
  86
  87  - The `lex' tool for generating lexical scanners.  The `flex'
  88    implementation recommended.  <http://flex.sourceforge.net/>
  89
  90  - The `awk' tool for data processing.  GNU Awk (`gawk') is
  91    recommended.  <http://www.gnu.org/software/gawk/>
  92
  93  - The CPython interpreter, version 2.7, including the development
  94    headers.  <https://www.python.org/downloads/>
  95
  96 The following tools and libraries are *highly recommended*:
  97
  98  - GNU `troff' (`groff'). <http://www.gnu.org/software/groff/>
  99
 100  - The freedesktop.org MIME info database.
 101    <http://freedesktop.org/Software/shared-mime-info>
 102
 103  - The freedesktop.org utilities for manipulating .desktop files.
 104    <http://www.freedesktop.org/software/desktop-file-utils>
 105
 106 The following tools and libraries are optional:
 107
 108  - `libstroke', a stroke and gesture recognition library.  If this is
 109    available, gschem will support mouse gesture recognition.
 110    <http://www.etla.net/libstroke/>
 111
 112  - The `doxygen' API documentation tool.  This is required for
 113    building the gEDA developer API documentation, not for the regular
 114    user documentation.  <http://www.stack.nl/~dimitri/doxygen/>
 115
 116  - `Inkscape' or `ImageMagic' for svg to png or pdf conversion
 117    This is required for building the gEDA developer API documentation,
 118    not for the regular user documentation.
 119    <http://inkscape.org/>
 120    <http://www.imagemagick.org/script/index.php>
 121
 122  - `Graphviz' for drawing directed graphs.
 123    This is required for building the gEDA developer API documentation,
 124    not for the regular user documentation.
 125    <http://www.graphviz.org/>
 126
 127 Troubleshooting dependencies
 128 ----------------------------
 129
 130   "I've installed the `libfoo' library, but `./configure' isn't
 131   picking it up!"
 132
 133 Many modern operating system distributions split a library into two
 134 packages:
 135
 136 1. a `libfoo' package, which contains the files necessary to
 137    *run* programs which use `libfoo'.
 138
 139 2. a `libfoo-dev' or `libfoo-devel' package, which contains the files
 140    necessary to *compile* programs which use `libfoo'.
 141
 142 If you're having problems, make sure that you have all of the
 143 necessary `dev' or `devel' packages installed.
 144
 145 Installation from a source archive
 146 ----------------------------------
 147
 148 First extract the archive to a sensible place:
 149
 150   tar -xzvf gEDA-gaf-<version>.tar.gz && cd gEDA-gaf-<version>
 151
 152 Run the configuration script.  You'll probably want to specify a
 153 custom directory to install gEDA to, for example:
 154
 155   ./configure --prefix=$HOME/geda
 156
 157 You can then compile gEDA:
 158
 159   make
 160
 161 And install it (if you used a `--prefix' outside your $HOME directory,
 162 you may need to run this as root):
 163
 164   make install
 165
 166 For more information on installing gEDA, see the `INSTALL' document.
 167
 168 Installation from the git repository
 169 ------------------------------------
 170
 171 gEDA uses the `git' version control system.  If you wish to try out
 172 the very latest version of gEDA, you will need to install some extra
 173 tools *in addition to* the ones listed above:
 174
 175   - The `git' version control tool, version 1.6 or newer.
 176     <http://git-scm.com/>
 177
 178   - GNU Automake, version 1.11.0 or newer.
 179     <http://www.gnu.org/software/automake/>
 180
 181   - GNU Autoconf, version 2.60 or newer.
 182     <http://www.gnu.org/software/autoconf/>
 183
 184   - GNU Libtool.  <http://www.gnu.org/software/libtool/>
 185
 186   - GNU Texinfo documentation system.
 187     <http://www.gnu.org/software/texinfo/>
 188
 189     Note that on some distributions the TeX support for Texinfo is
 190     packaged separately.
 191
 192 Once you have these installed, you need to clone the gEDA `git'
 193 repository:
 194
 195   git clone git://git.geda-project.org/geda-gaf.git
 196
 197 To generate the configure script, run:
 198
 199   ./autogen.sh
 200
 201 You can then procede to configure and build gEDA as described above.
 202 For more information on working with the gEDA `git' repository, see
 203 <http://wiki.geda-project.org/geda:scm>.
 204
 205 Building gEDA developer API documentation
 206 =========================================
 207
 208 Several of the gEDA libraries and applications have doxygen API
 209 documentation available.  To generate the API documentation from the
 210 source code, install doxygen (see `Dependencies' above).  Next, add
 211 `--enable-doxygen' to your configure command line, i.e.:
 212
 213   ./configure --enable-doxygen
 214
 215 To compile the documentation (quite a slow process), run:
 216
 217   make doxygen
 218
 219 The documentation can then be found in:
 220
 221   */docs/html/index.html
 222   */docs/latex/refman.pdf
 223
 224 Some modules don't automatically generate the PDF version of the
 225 documentation.  If you want them you have to build them explicitly,
 226 e.g.:
 227
 228   cd gattrib/docs && make refman.pdf
 229
 230 Getting help
 231 ============
 232
 233 There are several ways to get help with installing and using gEDA:
 234
 235  - The gEDA website <http://www.geda-project.org> has more extensive
 236    information on the gEDA tools, and links to some successful
 237    projects which use gEDA.
 238
 239  - The gEDA documentation wiki contains a large amount of helpful
 240    information.  A static copy is included with this distribution; see
 241    the `docs/wiki/index.html' file.  The wiki is accessible online at
 242    <http://wiki.geda-project.org/>.
 243
 244  - If the resources above didn't help you resolve your problem, or you
 245    are having a *design* problem that you want to get help with,
 246    consider subscribing to and posting your question to the
 247    `geda-user' mailing list.
 248    <http://wiki.geda-project.org/geda:mailinglists>
 249
 250  - Alternatively, you can add your question to the gEDA Answers page
 251    on Launchpad. <https://answers.launchpad.net/geda>
 252
 253  - If you have discovered a bug, have a feature request, or have
 254    written a patch to gEDA, please create an item on the gEDA Bugs
 255    page on Launchpad. <http://bugs.launchpad.net/geda>
 256
 257 License
 258 =======
 259
 260 gEDA/gaf (this package) is freely distributable under the GNU Public
 261 License (GPL) version 2.0 or (at your option) any later version.  See
 262 the `COPYING' file for the full text of the license.
 263
 264 The programs and associated files are:
 265
 266   Copyright (C) 1998-2013 by Ales Hvezda and the respective original
 267   authors.
 268
 269 See the `AUTHORS' file for a more extensive list of contributors to
 270 gEDA.
 271
 272 ..
 273    Local Variables:
 274    mode: text
 275    End: