Minor doc updates.
[wget] / INSTALL
1                                                             -*- text -*-
2                    GNU Wget Installation Procedure
3                    ===============================
4
5 0. Introduction
6 ---------------
7
8 This document describes how to build Wget from source code on
9 Unix-like systems.  If you want to install a precompiled Wget, this
10 document is not for you -- refer to the documentation provided by the
11 distributors instead.  If you already have Wget and want to learn how
12 to use it, refer to Wget's Info documentation or man page which you
13 should have received with your system.  If you are using Windows
14 (except for Cygwin), read windows/README instead.  If you want to
15 compile Wget from source code on a Unix-like system, read on.
16
17 The preferred form of building Wget is to get a release archive and
18 unpack it (which you have presumably done, since you are reading
19 this).  If you have obtained the source code via the Mercurial
20 repository, please follow the instructions in `README.checkout' before
21 continuing, as the sources from the Mercurial repository do not include
22 some files that are present in official distributions; these additional
23 files must be generated first.
24
25 1. Dependencies
26 ---------------
27
28 To build Wget, your system must support a Unix-like command-line
29 development environment, including the text-processing utilities (sh,
30 grep, awk, sed, etc.) and a functional C compiler.  On some GNU/Linux
31 systems, this means that you will need to install packages such as
32 `gcc', `glibc-devel' (or `libc6-dev') and `make'.  Most systems come
33 with these packages preinstalled, but it doesn't hurt to check.  If
34 you have successfully compiled other software from source, you
35 probably have them all.
36
37 In addition to the C development environment, Wget can use a number of
38 optional libraries to provide additional features, such as translated
39 messages and support for "https" URLs.  The "external" dependencies
40 include:
41
42   - OpenSSL -- for "https" URLs.
43   - GNU gettext -- for translated messages.
44   - GNU libidn -- for IDN/IRI support.
45   - GNU libiconv -- for IDN/IRI support (not needed on GNU).
46
47 To be usable for building Wget, the listed libraries must be installed
48 with their "development" header files.  On GNU/Linux systems this
49 typically means installing the corredponsing "lib<name>-devel" or
50 "lib<name>-dev" package along with the package with "lib<name>".
51
52 2. Configuration
53 ----------------
54
55 Before compiling Wget, you need to "configure" it using the
56 `configure' script provided with the distribution.  Configuration
57 serves two distinct purposes: it enables Wget's build system to
58 inspect certain features of your operating system for more robust
59 compilation, and it enables you to choose which features you want the
60 resulting Wget to have.
61
62 As is the case with most GNU software, Wget's configure script was
63 generated with GNU Autoconf.  If you're not familiar with
64 Autoconf-generated scripts, read on.
65
66 The most straightforward way to configure Wget is by running the
67 configure script without any arguments.  After running some
68 compilation-related tests, it will create the Makefiles needed to
69 build Wget.  However, you may wish to customize Wget's configuration
70 by providing arguments to `configure'.  Wget's configure script
71 accepts standard Autoconf arguments, the most important ones being:
72
73   --help                  display a help message and exit
74
75   --prefix=PREFIX         install architecture-independent files in PREFIX
76                           (/usr/local by default)
77   --bindir=DIR            user executables in DIR (PREFIX/bin)
78   --infodir=DIR           info documentation in DIR [PREFIX/info]
79   --mandir=DIR            man documentation in DIR [PREFIX/man]
80
81 For example, if you are not root and want to install Wget in
82 subdirectories of your home directory, you can use:
83
84     ./configure --prefix=$HOME
85
86 In addition to the above generic options, Wget's configuration
87 supports a number of options more or less specific to Wget.  Options
88 beginning with "--disable", such as `--disable-opie' or
89 `--disable-ntlm', allow you to turn off certain built-in functionality
90 you don't need in order to reduce the size of the executable.  Options
91 beginning with "--with" turning off autodetection and use of external
92 software Wget can link with, such as the SSL libraries.  Recognized
93 "--enable" and "--with" options include:
94
95   --without-ssl           disable SSL autodetection (used for https support)
96   --with-libssl-prefix=DIR search for libssl in DIR/lib
97   --disable-opie          disable support for opie or s/key FTP login
98   --disable-digest        disable support for HTTP digest authorization
99   --disable-ntlm          disable support for HTTP NTLM authorization
100   --disable-debug         disable support for debugging output
101   --disable-nls           do not use Native Language Support
102   --disable-largefile     omit support for large files
103   --disable-ipv6          disable IPv6 support
104   --disable-rpath         do not hardcode runtime library paths
105   --disable-iri           disable IDN/IRIs support
106
107 For the full list, see the output of `./configure --help'.
108
109 You can inspect decisions made by configure by editing the generated
110 Makefiles and the `src/config.h' include file.  The defaults should
111 work without intervention, but if you know what you are doing, editing
112 the generated files before compilation is fine -- they will not be
113 regenerated until you run configure again.
114
115 `configure' will try to find a compiler in your PATH, defaulting to
116 `gcc', but falling back to `cc' if the former is unavailable.  This is
117 a reasonable default on most Unix-like systems, but sometimes you
118 might want to override it.  The compiler choice is overridden by
119 setting the `CC' environment variable to the desired compiler file
120 name.  For example, to force compilation with the Unix `cc' compiler,
121 invoke configure like this:
122
123     ./configure CC=cc
124
125 This assumes that `cc' is in your path -- if it is not, simply use
126 CC=/path/to/cc instead.  Note that environment variables that affect
127 configure can be set with the usual shell syntax `VAR=value ./configure'
128 (assuming sh syntax), but can also be specified as arguments to
129 configure, as shown above.  The latter method, while being specific to
130 configure, works unmodified in all shells, and in addition allows
131 configure to detect when that setting has been changed across
132 invocations.
133
134 Environment variables that affect `configure' include: CFLAGS for C
135 compiler flags, CPPFLAGS for C preprocessor flags, LDFLAGS for linker
136 flags, and LIBS for libraries.
137
138 Barring the use of --without-* flags, configure will try to autodetect
139 external libraries needed by Wget, currently only the OpenSSL
140 libraries.  If they are installed in the system library directories or
141 in the same prefix where you plan to install Wget, configure should be
142 able to autodetect them.  If they are installed elsewhere, use the
143 `--with-libNAME' option to specify the root directory under which
144 libraries reside in the `lib/' subdirectory and the corresponding
145 header files reside in the `include/' subdirectory.  For example, if
146 the OpenSSL libraries are installed under the /usr/local/ssl prefix,
147 use `--with-libssl=/usr/local/ssl'.
148
149 Sometimes external libraries will be installed on the system, but the
150 header files will be missing.  This often happens on GNU/Linux if you
151 forget to install the "-devel" or "-dev" package that corresponds to
152 the library and that is typically *not* installed by default.  In that
153 case configure will not find the library and you will not be able to
154 use the features provided by the library until you install the devel
155 package and rerun configure.  If you believe you have the necessary
156 headers, but configure still fails to detect the library, please
157 report it as a bug.
158
159 3. Compilation
160 --------------
161
162 To compile GNU Wget after it has been configured, simply type make.
163 Wget requires a compiler and standard library compliant with the 1990
164 ISO C standard, which includes the vast majority of compilation
165 environments present on systems in use today.
166
167 After the compilation a ready-to-use `wget' executable should reside
168 in the src directory.  At this point there is no formal test suite for
169 testing the binary, but it should be easy enough to test whether the
170 basic functionality works.
171
172 4. Installation
173 ---------------
174
175 Use `make install' to install GNU Wget to directories specified to
176 configure.  To install it in a system directory (which is the
177 default), you will need to be root.  The standard prefix is
178 "/usr/local/", which can be changed using the `--prefix' configure
179 option.
180
181 The installation process will copy the wget binary to $PREFIX/bin,
182 install the wget.info* info pages to $PREFIX/info, the generated
183 manual page (where available) wget.1 to $PREFIX/man/man1, and the
184 default config file to $PREFIX/etc, unless a config file already
185 exists there.  You can customize these directories either through the
186 configuration process or making the necessary changes in the Makefile.
187
188 To delete the files created by Wget installation, you can use `make
189 uninstall'.