README

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