README.md

   1 General information
   2 ===================
   3 [![Build Status](https://travis-ci.org/ntd/adg.svg?branch=master)](https://travis-ci.org/ntd/adg)
   4 [![Coverage Status](https://coveralls.io/repos/ntd/adg/badge.svg?branch=master)](https://coveralls.io/r/ntd/adg?branch=master)
   5
   6 Automatic Drawing Generation is GObject-based library that provides
   7 a non-interactive cairo canvas specifically designed for generating
   8 technical drawings. It can be viewed as a tool for programmatically
   9 representing an abstract model into a layout (2D drafting).
  10
  11 If you want to develop an application that needs to show and print
  12 drawings where some data change but the overall design is similar,
  13 the ADG library can be quite useful. In manufacturing industries
  14 this is often the case and an ADG-based application could help to
  15 greatly improve the productivity of technical offices.
  16
  17 You could reach similar targets using parametric CADs but a custom
  18 application provides the following benefits:
  19
  20  * more customizable;
  21  * quicker and not so bloated as a parametric CAD;
  22  * can be easily connected to a database;
  23  * an ADG based filter can generate drawing on-fly: this feature
  24    could be used in web-based applications.
  25
  26 Visit the [ADG web site](http://adg.entidi.com/) for further
  27 details.
  28
  29
  30 Design overview
  31 ===============
  32
  33 The project is based on the [GObject](http://www.gtk.org/) library:
  34 the ADG canvas is developed in plain C using an object-oriented
  35 approach. Applications based on ADG are not expected to be
  36 developed in C, though: the basic idea is to have a set of bindings
  37 for higher level languages (the garbage-collected ones, above all).
  38 An application can then be developed using any specific language
  39 available, much in the same way as [GNOME](http://www.gnome.org/)
  40 applications are conceived.
  41
  42 Lua bindings based on [LGI](http://github.com/pavouk/lgi) are
  43 already availables and effectively used upstream to test the APIs.
  44 The [adg-lua](http://dev.entidi.com/p/adg-lua/) project provides
  45 code examples on how to use them.
  46
  47 The mathematical and geometrical algorithms, together with a bunch
  48 of other useful functions for manipulating cairo paths, are kept
  49 in a separated library called [CPML](http://adg.entidi.com/cpml/)
  50 (Cairo Path Manipulation Library). Although actually embedded into
  51 the ADG project, this library can be easily splitted on its own,
  52 if needed.
  53
  54 The rendering leverages [cairo](http://cairographics.org/), so the
  55 ADG canvas fully shares strong and weak points of that library.
  56 Most notably, the availables export formats include PostScript,
  57 SVG, PDF, PNG but no CAD specific ones (such as DXF). A complete
  58 list can be [browsed online](http://cairographics.org/backends/).
  59
  60
  61 External dependencies
  62 =====================
  63
  64 The ADG library has the following dependencies:
  65
  66  * [cairo](http://cairographics.org/) 1.7.4 or later, required by
  67    either CPML and ADG;
  68  * [GLib](http://www.gtk.org/) 2.14.0 or later, required by ADG;
  69  * [GTK+](http://www.gtk.org/) 3.0.0 or later (or GTK+ 2.12.0 or
  70    later for GTK+2 support) to optionally include GTK+ support and
  71    build the adg-demo program;
  72  * [pango](http://www.pango.org/) 1.18.0 or later (optional)
  73    to support a serious engine for rendering text instead of using
  74    the cairo "toy" APIs (only the pango-cairo module will be used);
  75  * [gtk-doc](http://www.gtk.org/gtk-doc/) 1.12 or later (optional),
  76    used to regenerate the API documentation
  77  * [GObject introspection](http://live.gnome.org/GObjectIntrospection)
  78    0.9.5 or later (optional) to dinamically generate bindings
  79    metadata.
  80
  81 The required packages must be installed prior the ADG building:
  82 they should be availables on nearly every decent unix-like system.
  83
  84 The ADG is mainly developed on GNU/Linux but its dependecies are
  85 known to be cross platform so a porting should be quite easy, if
  86 not automatic. Anyway, the cross-compilation of a Windows
  87 installer is supported upstream and it is based on the ArchLinux
  88 [Fedora mingw port](http://github.com/ntd/aur-fedora-mingw).
  89
  90
  91 Installation
  92 ============
  93
  94 The ADG build system is based on GNU autotools, the de-facto
  95 standard for handling free software projects. The following
  96 step-by-step instructions are included only for reference: you are
  97 free to install ADG in the way you prefer. Just remember if you
  98 are copying and pasting to put the proper package version instead
  99 of the 0.6.0 placeholder used in the examples.
 100
 101 1. Download the ADG tarball and put it somewhere into your file
 102    system (your home directory is a good candidate). You can
 103    browse the old releases or get the latest tarball directly
 104    from [SourceForge](http://sourceforge.net/projects/adg/files/).
 105
 106     ```
 107     cd $HOME
 108     wget http://sourceforge.net/projects/adg/files/adg/0.6.0/adg-0.6.0.tar.bz2
 109     ```
 110 2. Unpack the tarball:
 111
 112     ```
 113     tar xjvf adg-0.6.0.tar.bz2
 114     ```
 115 3. Configure the build. You can set different options while
 116    configuring: check the output of ./configure --help to get a
 117    list of all the available customizations.
 118
 119     ```
 120     cd adg-0.6.0
 121     ./configure
 122     ```
 123 4. Build the ADG library.
 124
 125     ```
 126     make
 127     ```
 128 5. Once the building has finished, you are able to run the demo
 129    program without installing anything. Just try it out by
 130    launching the uninstalled executable:
 131
 132     ```
 133     demo/adg-demo-uninstalled
 134     ```
 135 6. Install the library. You must have root privileges, either
 136    by previously logging in as root or by using the sudo command,
 137    if you intend to install it system-wide (the default). Anyway
 138    you can install to a custom destination where you have write
 139    access by explicitely setting the --prefix option in the
 140    configuration step.
 141
 142     ```
 143     sudo make install
 144     ```
 145
 146 Further details on the installation are availables in the INSTALL
 147 text file distributed within the tarball.