xref: /Universal-ctags/old-docs/INSTALL (revision 94eb5533b4afecf9ec7f085ede410daa2faa5c1f)
1Custom Installation
2===================
3
4These installation instructions are for Unix or Unix-like platforms (or at
5least, those platforms which are able to run a Bourne shell script). If you
6are attempting to install Exuberant Ctags on some other platform, see the file
7INSTALL.oth.
8
9If you are not familiar with using the configure scripts generated by GNU
10autoconf, read the "Basic Installation" section below; then return here.
11The configure script in this package supports the following custom options:
12
13  --disable-etags               By default, "make install" will install one
14                                binary, "ctags", one man page, "ctags.1", and
15                                create links to these two files by the names
16                                "etags" and "etags.1". If you do not want to
17                                install the "etags" links, use this option.
18
19  --disable-extended-format     Ctags now appends "extension flags" to the
20                                end of each tag entry in a manner which is
21                                backwards with original Vi implementation
22                                (they are placed into an EX comment). This
23                                can be disabled via use of the ctags --format
24                                option. This configure option changes the
25                                default behavior of ctags to disable use of
26                                these extension flags (i.e. use the original
27                                tag file format).
28
29  --disable-external-sort       Use this option to force use of an internal
30                                sort algorithm. On UNIX-like systems, ctags
31                                uses the sort utility of the operating system
32                                by default because it is more memory efficient.
33
34  --enable-custom-config=FILE   Defines a custom option configuration file to
35                                establish site-wide defaults. Ctags will read
36                                the following files at startup for options:
37                                /etc/ctags.conf, /usr/local/etc/ctags.conf,
38                                $HOME/.ctags, and .ctags. If you need a
39                                different file, set this option to the full
40                                path name of the file you want to be read, and
41                                it will be read immediately before reading
42                                $HOME/.ctags.
43
44  --enable-macro-patterns       By default, line numbers are used in the tag
45                                file for #define objects, in order to remain
46                                compatible with the original UNIX ctags. This
47                                option will make the default use patterns.
48
49  --enable-maintainer-mode      Creates a special GNU-specific version of the
50                                makefile which is used to maintain Exuberant
51                                Ctags.
52
53  --enable-tmpdir=DIR           When the library function mkstemp() is
54                                available, this option allows specifying the
55                                default directory to use for temporary files
56                                generated by ctags. This default can be
57                                changed at run time by setting the environment
58                                variable TMPDIR.
59
60If you wish to change the name of the installed files, edit the makefile
61produced by the configure script ("Makefile") before performing the "make
62install" step. There are two lines at the top of the file where the names of
63the installed files may be customized.
64
65
66Basic Installation
67==================
68
69   These are generic installation instructions.
70
71   The `configure' shell script attempts to guess correct values for
72various system-dependent variables used during compilation.  It uses
73those values to create a `Makefile' in each directory of the package.
74It may also create one or more `.h' files containing system-dependent
75definitions.  Finally, it creates a shell script `config.status' that
76you can run in the future to recreate the current configuration, a file
77`config.cache' that saves the results of its tests to speed up
78reconfiguring, and a file `config.log' containing compiler output
79(useful mainly for debugging `configure').
80
81   If you need to do unusual things to compile the package, please try
82to figure out how `configure' could check whether to do them, and mail
83diffs or instructions to the address given in the `README' so they can
84be considered for the next release.  If at some point `config.cache'
85contains results you don't want to keep, you may remove or edit it.
86
87   The file `configure.in' is used to create `configure' by a program
88called `autoconf'.  You only need `configure.in' if you want to change
89it or regenerate `configure' using a newer version of `autoconf'.
90
91The simplest way to compile this package is:
92
93  1. `cd' to the directory containing the package's source code and type
94     `./configure' to configure the package for your system.  If you're
95     using `csh' on an old version of System V, you might need to type
96     `sh ./configure' instead to prevent `csh' from trying to execute
97     `configure' itself.
98
99     Running `configure' takes awhile.  While running, it prints some
100     messages telling which features it is checking for.
101
102  2. Type `make' to compile the package.
103
104  3. Optionally, type `make check' to run any self-tests that come with
105     the package.
106
107  4. Type `make install' to install the programs and any data files and
108     documentation.
109
110  5. You can remove the program binaries and object files from the
111     source code directory by typing `make clean'.  To also remove the
112     files that `configure' created (so you can compile the package for
113     a different kind of computer), type `make distclean'.
114
115Compilers and Options
116=====================
117
118   Some systems require unusual options for compilation or linking that
119the `configure' script does not know about.  You can give `configure'
120initial values for variables by setting them in the environment.  Using
121a Bourne-compatible shell, you can do that on the command line like
122this:
123     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
124
125Or on systems that have the `env' program, you can do it like this:
126     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
127
128Compiling For Multiple Architectures
129====================================
130
131   You can compile the package for more than one kind of computer at the
132same time, by placing the object files for each architecture in their
133own directory.  To do this, you must use a version of `make' that
134supports the `VPATH' variable, such as GNU `make'.  `cd' to the
135directory where you want the object files and executables to go and run
136the `configure' script.  `configure' automatically checks for the
137source code in the directory that `configure' is in and in `..'.
138
139   If you have to use a `make' that does not supports the `VPATH'
140variable, you have to compile the package for one architecture at a time
141in the source code directory.  After you have installed the package for
142one architecture, use `make distclean' before reconfiguring for another
143architecture.
144
145Installation Names
146==================
147
148   By default, `make install' will install the package's files in
149`/usr/local/bin', `/usr/local/man', etc.  You can specify an
150installation prefix other than `/usr/local' by giving `configure' the
151option `--prefix=PATH'.
152
153   You can specify separate installation prefixes for
154architecture-specific files and architecture-independent files.  If you
155give `configure' the option `--exec-prefix=PATH', the package will use
156PATH as the prefix for installing programs and libraries.
157Documentation and other data files will still use the regular prefix.
158
159   In addition, if you use an unusual directory layout you can give
160options like `--bindir=PATH' to specify different values for particular
161kinds of files.  Run `configure --help' for a list of the directories
162you can set and what kinds of files go in them.
163
164Optional Features
165=================
166
167   Some packages pay attention to `--enable-FEATURE' options to
168`configure', where FEATURE indicates an optional part of the package.
169They may also pay attention to `--with-PACKAGE' options, where PACKAGE
170is something like `gnu-as' or `x' (for the X Window System).  The
171`README' should mention any `--enable-' and `--with-' options that the
172package recognizes.
173
174Sharing Defaults
175================
176
177   If you want to set default values for `configure' scripts to share,
178you can create a site shell script called `config.site' that gives
179default values for variables like `CC', `cache_file', and `prefix'.
180`configure' looks for `PREFIX/share/config.site' if it exists, then
181`PREFIX/etc/config.site' if it exists.  Or, you can set the
182`CONFIG_SITE' environment variable to the location of the site script.
183A warning: not all `configure' scripts look for a site script.
184
185Operation Controls
186==================
187
188   `configure' recognizes the following options to control how it
189operates.
190
191`--cache-file=FILE'
192     Use and save the results of the tests in FILE instead of
193     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
194     debugging `configure'.
195
196`--help'
197     Print a summary of the options to `configure', and exit.
198
199`--quiet'
200`--silent'
201`-q'
202     Do not print messages saying which checks are being made.  To
203     suppress all normal output, redirect it to `/dev/null' (any error
204     messages will still be shown).
205
206`--srcdir=DIR'
207     Look for the package's source code in directory DIR.  Usually
208     `configure' can determine that directory automatically.
209
210`--version'
211     Print the version of Autoconf used to generate the `configure'
212     script, and exit.
213
214`configure' also accepts some other, not widely useful, options.
215
216