INSTALL

   1 Installing adesklets
   2 ********************
   3
   4 Compilation Requirements
   5 ========================
   6
   7 To compile adesklets from source, you will need:
   8
   9    * A compiler supporting ANSI C plus variadic macros (about every
  10      version of gcc  from 2.7.0 will do - or about everything else
  11      published in the last ten years, for that matter)
  12
  13    * X11  libraries and headers(1)
  14
  15    * Imlib2 1.1.2 and up (the more recent the better; go and fetch it
  16      from http://sourceforge.net/projects/enlightenment/ )
  17
  18    * GNU readline
  19
  20    * A reasonably POSIX-compliant system
  21
  22 It can also use, if present in the system:
  23
  24    * fontconfig , for automated detection of all usable fonts present
  25      in the system
  26
  27    * GNU history , the faithful complement to GNU readline for command
  28      history support: _it is required to have it for all the desklets
  29      using interactive mode of execution_
  30
  31    * iconv library and headers (such as libiconv ), for
  32      internationalization support (dynamic support of extended
  33      character sets)
  34
  35    * Python  2.3 and up, if you want Python support (you most probably
  36      do - desklets are written in this language)
  37
  38    Many systems routinely package "development" versions of libraries
  39 and tools separately (`imlib2-devel', `readline-devel',
  40 `fontconfig-devel', `python-devel', etc); if this is the case for the
  41 target system, those have to be chosen over the "regular" versions.
  42
  43 Runtime requirements
  44 ====================
  45
  46 In addition to the compilation requirements, the optional adesklets
  47 shell frontend, installed by default, will itself need a few utilities,
  48 all expected to minimally comply with POSIX 1003.2 and 1003.2a
  49 specifications:
  50
  51    * a sh-compatible `/bin/sh' shell
  52
  53    * a Streaming EDitor (sed)
  54
  55    * test, mkdir, rmdir, sleep, kill and ls
  56
  57    The `xwininfo' and `xprop' programs can also be used by this
  58 frontend, if a given fake-root window detection routine is explicitely
  59 invoked. Both XFree86 and X.org implementations of these utilities have
  60 been tested. Other programs will eventually be used by specific
  61 detection routine: see the frontend source for details.
  62
  63 Portability Notice
  64 ==================
  65
  66 This package was built with portability in mind: all vendor-specific
  67 extensions were avoided, and specs (ANSI, SVID 3, BSD 4.3, POSIX) were
  68 followed in a conservative way. Nevertheless, original development took
  69 place on a single Linux system; it is quite probable that adesklets
  70 will not compile or work as expected in some cases. Fixing portability
  71 issues is an important concern for us.
  72
  73    adesklets has been ported and successfully tested by the developers
  74 on many systems. As of version 0.5.1, it has been verified to compile
  75 and run out of the box on a variety of
  76
  77    * *Kernels/Systems*: Linux (2.2, 2.4, 2.6 series), FreeBSD
  78      (4.10, 5, 6 and 7), NetBSD (1.6), OpenBSD (3.8)
  79
  80    * *C Libraries* (when applicable): glibc (2.1.3 and up), uclibc
  81      (0.9.28)
  82
  83    * *Compilers*: gcc (2.95.2, whole 3 serie, 4.0.2),       icc 7.0
  84      (with tweaking)
  85
  86    Moreover, adesklets itself is fully architecture independent,
  87 although Imlib2 is further optimized for the x86 and amd64. It is
  88 routinely used on x86, amd64 and ppc machines by the author.
  89
  90    At the time of writing, adesklets is already integrated in ports
  91 collections of many BSD and software libraries of linux distributions.
  92 For reference, let's mention:
  93
  94    * Debian package: http://packages.debian.org/unstable/x11/adesklets ,
  95      maintained by Bartosz Fenski <fenio@debian.org>.
  96
  97    * FreeBSD port: http://www.freshports.org/deskutils/adesklets/ ,
  98      maintained by Roman Bogorodskiy <novel@freebsd.org>.
  99
 100    Did you try to run the package on something not listed here?  Let us
 101 know, especially if it did not work.
 102
 103 Software download
 104 =================
 105
 106 The current version of the software (as a source bzip'ed tarball) can
 107 be found on the SourceForge project page:
 108 http://sf.net/projects/adesklets/
 109
 110    You can extract it from the console with `tar'. As of version 0.5.1,
 111 the command line would be:
 112
 113      tar xvjf adesklets-0.5.1.tar.bz2
 114
 115    or, if your installed version of `tar' does not support filtering
 116 archives through bzip2:
 117
 118      bzcat adesklets-0.5.1.tar.bz2 | tar xv
 119
 120 Verifying Software Integrity (optional)
 121 =======================================
 122
 123 As of adesklets 0.5.1,  you can also download from SourceForge  an
 124 ascii-armored detached signature named `adesklets-0.5.1.tar.bz2.asc',
 125 that you can match against the author's Open PGP public key (*note Open
 126 PGP Public Key::, in appendix) to assert the package integrity. For
 127 instance, with `GnuPG' (http://www.gnupg.org/ ), you would use:
 128
 129      gpg --verify adesklets-0.5.1.tar.bz2.asc adesklets-0.5.1.tar.bz2
 130
 131    You can also get the public key for <syfou@users.sourceforge.net>
 132 from various public key servers such as http://www.keyserver.net/  or
 133 http://pgp.mit.edu/ . Feel free to contact the author directly if you
 134 want to authenticate the key further.
 135
 136 Compilation and Installation:
 137 =============================
 138
 139 adesklets provides the usual autoconf/automake scripts of GNU packages.
 140
 141    Therefore, in most cases, installation follows the normal three
 142 steps:
 143
 144   1. `cd' to the directory containing the package's source code and type
 145      `./configure' to configure the package for your system.  If you're
 146      using `csh' on an old version of System V, you might need to type
 147      `sh ./configure' instead to prevent `csh' from trying to execute
 148      `configure' itself.
 149
 150      Running `configure' takes awhile.  While running, it prints some
 151      messages describing which features it is checking for.
 152
 153   2. Type `make' to compile the package.
 154
 155   3. Type `make install' to install the programs and any data files and
 156      documentation.
 157
 158    You can remove the program binaries and object files from the source
 159 code directory by typing `make clean'.  To also remove the files that
 160 `configure' created (so you can compile the package for a different
 161 kind of computer), type `make distclean'.
 162
 163 Compilers and Options:
 164 ======================
 165
 166 Some systems require unusual options for compilation or linking that
 167 the `configure' script does not know about.  You can give `configure'
 168 initial values for variables by setting them in the environment.  Using
 169 a Bourne-compatible shell, you can do that on the command line like
 170 this:
 171
 172      CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
 173
 174 Or on systems that have the `env' program, you can do it like this:
 175
 176      env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
 177
 178 Optional Features:
 179 ==================
 180
 181 adesklets comes with a few optional features you can select or not from
 182 the `configure' script. Type:
 183
 184      ./configure --help
 185
 186 for a complete, short description. Here are a few interesting ones:
 187
 188    * You may choose to compile adesklets without X support at all
 189      (`--without-x').  You will get a version that is obviously not
 190      suited for desklets rendering, but still good for command line
 191      image manipulation
 192
 193    * You can remove support for some others packages as well:
 194      `--without-history', `--without-fontconfig'
 195
 196    * The shell frontend can be avoided altogether using:
 197      `--disable-frontend-shell-driver'
 198
 199    ---------- Footnotes ----------
 200
 201    (1) Except for headless builds, useful for server environments and
 202 such; read further for details.
 203