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