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 `libfam' or `libgamin' client library to interface the File
 107    Alteration Monitor daemon.  If this is available, gschem will
 108    detect if files have been changed on disk by another application.
 109    <http://oss.sgi.com/projects/fam/>
 110
 111 The following tools and libraries are optional:
 112
 113  - The `doxygen' API documentation tool.  This is required for
 114    building the gEDA developer API documentation, not for the regular
 115    user documentation.  <http://www.stack.nl/~dimitri/doxygen/>
 116
 117  - `Inkscape' or `ImageMagic' for svg to png or pdf conversion
 118    This is required for building the gEDA developer API documentation,
 119    not for the regular user documentation.
 120    <http://inkscape.org/>
 121    <http://www.imagemagick.org/script/index.php>
 122
 123  - `Graphviz' for drawing directed graphs.
 124    This is required for building the gEDA developer API documentation,
 125    not for the regular user documentation.
 126    <http://www.graphviz.org/>
 127
 128 Troubleshooting dependencies
 129 ----------------------------
 130
 131   "I've installed the `libfoo' library, but `./configure' isn't
 132   picking it up!"
 133
 134 Many modern operating system distributions split a library into two
 135 packages:
 136
 137 1. a `libfoo' package, which contains the files necessary to
 138    *run* programs which use `libfoo'.
 139
 140 2. a `libfoo-dev' or `libfoo-devel' package, which contains the files
 141    necessary to *compile* programs which use `libfoo'.
 142
 143 If you're having problems, make sure that you have all of the
 144 necessary `dev' or `devel' packages installed.
 145
 146 Installation from a source archive
 147 ----------------------------------
 148
 149 First extract the archive to a sensible place:
 150
 151   tar -xzvf gEDA-gaf-<version>.tar.gz && cd gEDA-gaf-<version>
 152
 153 Run the configuration script.  You'll probably want to specify a
 154 custom directory to install gEDA to, for example:
 155
 156   ./configure --prefix=$HOME/geda
 157
 158 You can then compile gEDA:
 159
 160   make
 161
 162 And install it (if you used a `--prefix' outside your $HOME directory,
 163 you may need to run this as root):
 164
 165   make install
 166
 167 For more information on installing gEDA, see the `INSTALL' document.
 168
 169 Installation from the git repository
 170 ------------------------------------
 171
 172 gEDA uses the `git' version control system.  If you wish to try out
 173 the very latest version of gEDA, you will need to install some extra
 174 tools *in addition to* the ones listed above:
 175
 176   - The `git' version control tool, version 1.6 or newer.
 177     <http://git-scm.com/>
 178
 179   - GNU Automake, version 1.11.0 or newer.
 180     <http://www.gnu.org/software/automake/>
 181
 182   - GNU Autoconf, version 2.60 or newer.
 183     <http://www.gnu.org/software/autoconf/>
 184
 185   - GNU Libtool.  <http://www.gnu.org/software/libtool/>
 186
 187   - GNU Texinfo documentation system.
 188     <http://www.gnu.org/software/texinfo/>
 189
 190     Note that on some distributions the TeX support for Texinfo is
 191     packaged separately.
 192
 193 Once you have these installed, you need to clone the gEDA `git'
 194 repository:
 195
 196   git clone git://git.geda-project.org/geda-gaf.git
 197
 198 To generate the configure script, run:
 199
 200   ./autogen.sh
 201
 202 You can then procede to configure and build gEDA as described above.
 203 For more information on working with the gEDA `git' repository, see
 204 <http://wiki.geda-project.org/geda:scm>.
 205
 206 Building gEDA developer API documentation
 207 =========================================
 208
 209 Several of the gEDA libraries and applications have doxygen API
 210 documentation available.  To generate the API documentation from the
 211 source code, install doxygen (see `Dependencies' above).  Next, add
 212 `--enable-doxygen' to your configure command line, i.e.:
 213
 214   ./configure --enable-doxygen
 215
 216 To compile the documentation (quite a slow process), run:
 217
 218   make doxygen
 219
 220 The documentation can then be found in:
 221
 222   */docs/html/index.html
 223
 224 The PDF version of the documentation isn't generated by default.
 225 If you want it, you have to build it explicitly, e.g.:
 226
 227   cd $(srcdir)/libgeda/docs/latex && make
 228
 229 Getting help
 230 ============
 231
 232 There are several ways to get help with installing and using gEDA:
 233
 234  - The gEDA website <http://www.geda-project.org> has more extensive
 235    information on the gEDA tools, and links to some successful
 236    projects which use gEDA.
 237
 238  - The gEDA documentation wiki contains a large amount of helpful
 239    information.  A static copy is included with this distribution; see
 240    the `docs/wiki/index.html' file.  The wiki is accessible online at
 241    <http://wiki.geda-project.org/>.
 242
 243  - If the resources above didn't help you resolve your problem, or you
 244    are having a *design* problem that you want to get help with,
 245    consider subscribing to and posting your question to the
 246    `geda-user' mailing list.
 247    <http://wiki.geda-project.org/geda:mailinglists>
 248
 249  - Alternatively, you can add your question to the gEDA Answers page
 250    on Launchpad. <https://answers.launchpad.net/geda>
 251
 252  - If you have discovered a bug, have a feature request, or have
 253    written a patch to gEDA, please create an item on the gEDA Bugs
 254    page on Launchpad. <http://bugs.launchpad.net/geda>
 255
 256 License
 257 =======
 258
 259 gEDA/gaf (this package) is freely distributable under the GNU Public
 260 License (GPL) version 2.0 or (at your option) any later version.  See
 261 the `COPYING' file for the full text of the license.
 262
 263 The programs and associated files are:
 264
 265   Copyright (C) 1998-2013 by Ales Hvezda and the respective original
 266   authors.
 267
 268 See the `AUTHORS' file for a more extensive list of contributors to
 269 gEDA.
 270
 271 ..
 272    Local Variables:
 273    mode: text
 274    End: