INSTALL

   1 Elinks installation guidelines
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4   Quick guide for the impatient:
   5
   6         ./configure && make && make install
   7
   8   Check out the bottom of this file if you're upgrading from Links or an older
   9 ELinks! And be sure to look at doc/ecmascript.txt if you want (experimental)
  10 ECMAScript (that's JavaScript) support.
  11
  12 ##########
  13
  14   In order to check out the latest tree from GIT (using Cogito):
  15
  16         $ cg clone check_file_SITES_for_value_of_this
  17         $ cd elinks
  18
  19   To update your existing tree to the latest GIT version, do:
  20
  21         $ cg update
  22
  23   If you downloaded a nightly snapshot, and want to check out the latest tree
  24 from GIT in it, use the command:
  25
  26         $ cg clone -s check_file_SITES_for_value_of_this
  27
  28   Note that if you obtained the sources directly from GIT, you NEED to run
  29
  30 ./autogen.sh!  (It should be enough to do it once - however, if you have build
  31
  32 problems, try running this first.) Also, you obviously need GNU make and
  33 autoconf installed on your system (note that autoconf-2.13 is supported, newer
  34 ones may cause problems thanks to the autoconf developers who don't know how to
  35 maintain backwards compatibility).  Otherwise, you have to use the nightly GIT
  36 snapshot - you don't need to do this there.
  37
  38
  39 ##########
  40
  41   If you want to compile ELinks, first check the directory named contrib/, it
  42 may contain patches that are of use to you.  If you're interested in any of
  43 them, try to apply them by doing (for each one):
  44
  45         $ patch -p0 < contrib/that-patch
  46
  47   They may not apply, since I don't update patches in contrib/ regularly - if
  48 you want, feel free to go ahead and update the patch for the current tree and
  49 submit the newer version.
  50
  51   The compilation itself looks like:
  52
  53   Unix - just doing:
  54
  55          $ ./configure
  56          $ make
  57
  58          should be enough.  However, in some FreeBSD 3 distributions you have to
  59          set CFLAGS=-aout before running ./configure.  Also, you may want to
  60          adjust some (well, plenty of) compile-time options through ./configure
  61          - do ./configure --help and it'll print out a list of them. You can
  62          finetune what's going to be included in the binary in the features.conf
  63          file, and some really detailed tuning can be performed in src/setup.h.
  64
  65          Also, a nice idea is to compile ELinks outside of the source tree (note
  66          that this might not quite work right now, but we're working on fixing
  67          it). Make another directory and run path_to_source_tree/configure from
  68          it. Typically, it looks like:
  69
  70          $ mkdir ../elinks-build
  71          $ cd ../elinks-build
  72          $ ../elinks/configure
  73          $ make
  74
  75   OS/2 - you can use ./configure.
  76
  77          The only supported compiler is EMX, you probably won't be able to
  78          compile it with anything else.
  79
  80          Configure under OS/2 needs to know paths to gcc, make and bash.
  81          Set (for example):
  82
  83          SET HOSTTYPE=i586
  84          SET MACHTYPE=i586-pc-os2
  85          SET CONFIG_SHELL=d:/prg/gnu/bin/bash.exe
  86          SET CC=d:/prg/emx/bin/gcc.exe
  87          SET MAKE=d:/prg/emx/bin/make.exe
  88          SET EMXOPT=-h100
  89
  90   DOS, Windows - port it by yourself.
  91
  92   Usually, even after strip, the ELinks binary can measure a lot, but you can
  93 radically reduce the resulting binary size by throwing out stuff you don't like.
  94 Detailed discussion of reducing the executable size can be found in
  95
  96         doc/small.txt
  97
  98
  99 ##########
 100
 101   Ok, now let's install it:
 102
 103   Unix - # make install
 104
 105   OS/2 -
 106         Copy file links.exe somewhere to your path or create CMD file that runs
 107         links.
 108
 109          WARNING: EMX has a nasty limit on open files.  Links will work badly or
 110          won't work with the default settings.  Set the variable EMXOPT=-h100
 111          before you run links.
 112
 113   Now, check the contrib/ directory again.  There may be some useful config
 114 file examples there, along with few support tools and some Lua scripts - you
 115 probably want them ;) so just copy hooks.lua to ~/.elinks, and edit the
 116 configuration part - it adds various functionality to ELinks, like
 117 decompression of gzipped files or HTML code rewriting for ELinks-unfriendly
 118 websites.
 119
 120
 121   !BEWARE!  If you _distribute_ an ELinks executable linked with OpenSSL and
 122 the OpenSSL library is not part of your base system, you are VIOLATING THE GPL.
 123 I honestly believe that for this absurd case no ELinks copyright holder will
 124 sue you, and it's not a problem for the OpenSSL people as well, as they have
 125 explicitly told me, but you might stay on the safe side.
 126
 127   So, people who are making ELinks binaries for systems with no OpenSSL in the
 128 base system and who decided to link OpenSSL against the ELinks binary may wish
 129 NOT to publish or distribute such an executable, as it's breaking GPL 2(b), if
 130 they like to have everything legally perfect (like the Debian people ;-).
 131
 132   As a semi-solution to this problem, GNUTLS support was introduced; if you want
 133 to distribute ELinks executables with HTTPS support, compile ELinks with the
 134 --with-gnutls configure option (assuming that you have GNUTLS 1.2.0 installed;
 135 we can't say about later versions since GNUTLS people seem to have strange taste
 136 wrt. backwards compatibility).
 137
 138   HOWEVER, beware that GNUTLS support in ELinks is not so well tested as
 139 OpenSSL, and shall be probably still considered experimental. Therfore, it's
 140 recommended to the users to give OpenSSL strong preference whenever possible.
 141 (Just to show the GNU ideologists how silly can they sometimes be, if not
 142 anything else. ;-)
 143
 144
 145 ##########
 146
 147   If you're upgrading from Links or older ELinks (0.4pre7 or older), you will
 148 notice that several things have changed.  First, the binary name is elinks, not
 149 links, now; however, the basic usage is almost the same and it still looks like
 150 the old (E)Links, so you probably want to make a links symlink pointing to
 151 elinks.
 152
 153   Then, note that configuration files were moved from /etc to /etc/elinks and
 154 from ~/.links to ~/.elinks, because the name and format of some of them was
 155 changed:
 156
 157   links.cfg became elinks.conf and you need to convert it with
 158 contrib/conv/conf-links2elinks.pl; html.cfg was merged into elinks.conf.
 159
 160   bookmarks are still bookmarks, but you need to convert it with
 161 old_to_new_bookmarks.sh.
 162
 163   links.his became gotohist and the format is the same.
 164
 165   history became globhist and the format is the same.
 166
 167   cookies are still cookies, but you need to convert it with tr " " "\t".
 168
 169
 170 ##########
 171
 172 $Id: INSTALL,v 1.29 2004/09/22 16:17:23 pasky Exp $
 173 vim: textwidth=80