Debian Codegraph @

INSTALL.en.adoc

raw
1 // -*- coding: utf-8 -*-
2 :source-highlighter: pygments
3
4
5 = Compiling and Installing Gauche
6
7 NOTE: The Gauche system is a work in progress and frequently updated.
8 Check out the latest information on the site:
9 https://practical-scheme.net/gauche/
10
11 This document explains how to compile and install Gauche from a distributed
12 tarball. To compile from cloned source tree from the repository,
13 you need some extra steps; See the file link:HACKING.adoc[] for the details.
14
15
16 == Prerequisites
17
18
19 You need the standard build tools of the Unix environment, and
20 GNU make.
21
22 Besides that, the following
23 tools and libraries are recommended to have. You can build Gauche without
24 them, but some features won't be available.
25
26 - Makeinfo (version 5.0 or later) - used to build info document.
27 If the build platform doesn't have it, document building is skipped and info
28 document won't be installed. (You need info document to use online document
29 browsing from REPL.)
30 - Gzip - also used during document building.
31 - Libiconv - Used for character encoding conversion. See below.
32 - link:https://tls.mbed.org/[Mbed TLS] - Used for TLS/SSL connection. See below.
33
34 There are other optional libraries, which will be explained below.
35
36 To build on Windows, you can use MSYS/MinGW.
37 See link:doc/HOWTO-mingw.adoc[] for the details.
38
39
40 == Quick Start
41
42 [source,console]
43 ----
44 % ./configure
45 % make
46 % make check
47 % make install
48 ----
49
50 Things will be installed under `/usr/local/bin`, `/usr/local/lib/gauche`,
51 and `/usr/local/share/gauche`.
52
53 If you have installed Gauche before, and want to install
54 new version of Gauche with the same configuration option,
55 you can use the following command instead of `configure`.
56
57 [source,console]
58 ----
59 % gauche-config --reconfigure | sh
60 ----
61
62 When the option `--reconfigure` is given, `gauche-config` prints out
63 the command line when it is configured. Pass the output to
64 shell and you can reconfigure with the same options. It is a
65 convenient way to update Gauche.
66
67
68 == TLS/SSL support
69
70 Gauche relies on link:https://tls.mbed.org/[MbedTLS] for secure
71 connection support.
72
73 By default, `configure` checks if the MbedTLS library is installed
74 on the system, and use it if it's available. Otherwise, no TLS support
75 is compiled. If you can't install MbedTLS for some reason,
76 or you want to bring the compiled binary to the target system that
77 may not have MbedTLS library, you can specify to download MbedTLS
78 source during build and compile it into Gauche binary.
79
80 [horizontal]
81 `--with-tls=none` :: do not include TLS/SSL support
82 `--with-tls=mbedtls` :: include only mbedTLS support
83 `--with-tls=mbedtls-internal` :: During the build, MbedTLS source is downloaded
84 and compiled with Gauche. See below.
85
86
87 If you give `mbedtls-internal` in place of `mbedtls`, the build process downloads
88 MbedTLS source and compile it into Gauche's extension library. The resulting
89 binary doesn't depend on system's MbedTLS dynamic library, so you can move it
90 to the systems that don't have MbedTLS. You need CMake to use this option.
91 Note that if you use `mbedtls-internal`, MbedTLS code is included in
92 `rfc--tls--mbed.so` and `libgauche-static-*.a`, so they are subject to the
93 MbedTLS license as well (Apache License 2.0).
94
95 MbedTLS library can be compiled with or without multi-threading support.
96 Gauche requires MbedTLS library to be compiled with multi-threading support.
97 If the system's library doesn't have that support, use the option to
98 build it into Gauche library.
99
100 If you use TLS, you need CA certificates bundle to validate
101 server certificates. You may specify several options where to look for one.
102
103 [horizontal]
104 `--with-ca-bundle=check` :: Use heuristics to find CA bundle (default)
105 `--with-ca-bundle=none` :: Do not set default CA bundle
106 `--with-ca-bundle=system` :: Use system CA bundle.
107 On MinGW, it accesses system CA store via
108 Windows API. Otherwise, it checks several
109 known paths used for popular systems.
110 `--with-ca-bundle=<path>` :: Use given path as the CA bundle file
111
112
113 See the manual's `rfc.tls` entry for the details.
114
115
116 == Common command names
117
118 SRFI (Scheme Requrests for Implementation), where various aspects of
119 Scheme spec are discussed, suggests some common names for Scheme-related
120 commands if the implementation comforms certain specs. Those command
121 names may be used by other implementation, so we don't install them
122 by default.
123
124 If you give `--enable-shared-commands` option, the following commands are
125 installed:
126
127
128 `scheme-r7rs`, `scheme-srfi-0`, `scheme-srfi-7`::
129 Aliases of `gosh`.
130
131 `compile-r7rs`::
132 Alias of `gauche-compile-r7rs`.
133
134
135
136 == DBM database support
137
138 By default, Gauche looks for gdbm, ndbm and odbm (original dbm) libraries
139 on your system, and build support for available libraries.
140
141 If you want to exclude any of these support, list the libraries you
142 want to *inlucde* in `--with-dbm` configure option. For example,
143 if you want to include ndbm and odbm but nothing else,
144 specify `--with-dbm=ndbm,odbm`.
145 If you want to include none of them, specify `--with-dbm=no`.
146
147
148 == Character encoding conversion
149
150 Gauche can recognize and converts Unicode (UTF-8, 16, 32), Latin-N, and
151 typical japanese character encodings, but delegates other conversion work
152 to iconv library (when available). If your system does not have iconv
153 installed in the standard location, you can specify the location of your
154 external iconv library by `--with-iconv` option.
155
156 [source,sh]
157 ----
158 --with-iconv=DIR
159 ----
160
161
162 For example, if your say `--with-iconv=/usr/local`, Gauche looks
163 for the header iconv.h from `/usr/local/include` and the library
164 libiconv from `/usr/local/lib`.
165 In case if your iconv library is named other than libiconv, say,
166 `libmyconv`, you can also specify `--with-iconv-lib=myconv` to tell
167 Gauche to link against the library.
168
169 You can obtain Bruno Haible's libiconv library from here:
170 https://www.gnu.org/software/libiconv/
171
172
173 == Local library paths
174
175 If you want to use some libraries installed in non-standard location
176 to build Gauche, you can use the following option to specify the
177 locations.
178
179 [source,sh]
180 ----
181 --with-local=PATH:PATH2:...
182 ----
183
184 This addts `PATH/include`, `PATH2/include`, ... to the include paths,
185 and `PATH/lib`, `PATH2/lib`, ... to the library search paths.
186
187 For example, if you want to use gdbm library in `/usr/local`,
188 you can say:
189
190 [source,sh]
191 ----
192 --with-local=/usr/local
193 ----
194
195
196 == Selecting SLIB location
197
198 link:http://people.csail.mit.edu/jaffer/SLIB[SLIB]
199 is a portable Scheme library containing various useful functions,
200 entirely written in Scheme. Gauche can use SLIB features if you have
201 it on your system.
202
203 The configure script tries to find where SLIB is installed. It looks
204 for some typical directories like `/usr/local/slib` or `/usr/share/slib`.
205 If you installed your SLIB in some non-standard location, you can tell
206 it to the configure script as follows:
207
208 [source,sh]
209 ----
210 ./configure --with-slib=PATH
211 ----
212
213 where `PATH` is the path you installed your SLIB.
214
215 Gauche works without SLIB, anyway. If you're not interested, you
216 don't need to care about this.
217
218 SLIB needs a catalog file to be created in the Gauche library
219 directory before use. If Gauche finds SLIB during installation,
220 the install procedure creates the catalog file.
221 If you install slib after installing Gauche, it tries to create
222 the catalog file when you use slib first time, and you may get
223 an error if you don't have a permission to write into the
224 Gauche library directory. Run `gosh` in the right permission
225 and evaluate something like the following will solve the problem.
226
227 [source,scheme]
228 ----
229 (use slib)
230 (require 'logical)
231 ----
232
233
234 == Run-time library path
235
236 In some cases, your have to run Gauche under the environment
237 you don't have much control. One of such cases is when you
238 want to run CGI script on the ISP's machine. It may become
239 a problem that your build of Gauche depends on some dynamically
240 loaded libraries that are installed in non-standard location.
241
242 For example, suppose you install a new `libiconv.so` in `/home/yours/lib`
243 on the ISP's server and compile Gauche with `--with-iconv=/home/yours/lib`.
244 You have set up correct environment variables such as `LD_LIBRARY_PATH`,
245 so you can invoke Gauche interpreter `gosh` without a problem. Now,
246 you write a CGI script. Unfortunately, the ISP's web server
247 doesn't set `LD_LIBRARY_PATH` as you desired, and your script never
248 runs on the server, for the interpreter can't find `libiconv.so`
249 in the system default path.
250
251 Some compilers have an option that writes exact path of shared
252 libraries that the binary depends on. A `configure` option `--with-rpath`
253 utilizes the feature. When an option `--with-rpath=DIR` is given,
254 configure sets up a build process so that the shared libraries
255 are looked from `DIR`. This works only on `gcc`, however.
256
257
258 == Customizing install location
259
260 Call configure with those parameters to specify where to install.
261
262 [source,console]
263 ----
264 % ./configure --prefix=$PREFIX --exec-prefix=$EXEC_PREFIX
265 ----
266
267
268 If `--prefix` option is omitted, `/usr/local` is assumed as `PREFIX`.
269 If `--exec-prefix` option is omitted, `EXEC_PREFIX` is set the same as `PREFIX`.
270
271
272 The files are installed in those locations:
273
274 `$EXEC_PREFIX/bin/*`::
275 The interpreter (`gosh`) and configuration script (`gauche-config`).
276
277 `$EXEC_PREFIX/lib/*`::
278 Library (`libgauche.a`).
279
280 `$PREFIX/share/gauche/VERSION/include/*`::
281 Header files required to create applications using libgauche.
282
283 `$PREFIX/share/gauche/VERSION/lib/*`::
284 Machine-independent Scheme files.
285
286 `$PREFIX/share/info/*`::
287 info files.
288
289 `$EXEC_PREFIX/lib/gauche/VERSION/ARCHITECTURE/*`::
290 Machine-dependent files (`.so` files, `gosh`, `gauche-config`, and `libgauche.a`)
291
292 `$PREFIX/share/gauche/site/lib/*`::
293 `$EXEC_PREFIX/lib/gauche/site/VERSION/ARCHITECTURE/*`::
294 These are default locations where user installed
295 machine-independent/dependent files will go.
296
297
298 == Optimization options
299
300
301 You can pass extra options at make time, using `make` macro `OPTFLAGS`.
302 `configure` sets a default, but if you want to explore different
303 options, just run `make` as follows:
304
305 [source,sh]
306 ----
307 make OPTFLAGS="--some-compiler-option --other-option"
308 ----
309
310
311 == Uninstallation
312
313 You can remove installed Gauche software by running
314
315 [source,sh]
316 ----
317 make uninstall
318 ----
319
320 on top of the source tree.
321
322
323 == Cross compilation
324
325 Gauche supports autotools-standard cross compilation, that is,
326 you give `--build` and `--host` option to `configure` script and
327 just make (assuming you have appropriate cross development tools).
328 There are a couple of caveats, though.
329
330 - You have to have the same version of Gauche that you're trying to
331 cross-compile on the build machine.
332 +
333 In normal build, Gauche uses freshly built `gosh` to compile
334 extension libraries (under `ext/`). While cross compiling we can't run
335 freshly built `gosh` on the build machine, so we rely on the `gosh` already
336 installed on it.
337
338 - You may need `--with-libatomic-ops=no` option for `./configure`
339 +
340 The option forces Gauche to use bundled `libatomic_ops` source instead
341 of system provided one. We noticed that `./configure` may misunderstood
342 the build system's `libatmic_ops` as the host system's.
343
344 For example, the following command line is to cross build on your machine
345 for Windows (mingw-w64 32bit):
346
347 [source,sh]
348 ----
349 ./configure --build=`./config.guess` \
350 --host=i686-w64-mingw32 \
351 --with-libatomic-ops=no \
352 --prefix=/usr/local
353 ----
354
355 == Machine-dependent information
356
357
358 * MacOS X - 10.15 (Catalina) enhanced the security check, and doesn't allow
359 to execute shell scripts extracted from an unsigned downloaded tarball.
360 Run the following command after extractng tarball
361 (Replace VERSION for Gauche's version).
362 You can check if the tarball isn't tampered using asc signature file
363 distributed from https://practical-scheme.net/vault/.
364 +
365 [source,sh]
366 ----
367 xattr -r -d com.apple.quarantine Gauche-VERSION/
368 ----
369
370 * IRIX with 64bit binary - If you want to compile for 64bit ABI instead
371 of the default 32bit ABI, run configure like this:
372 +
373 [source,sh]
374 ----
375 CC="cc -64" AS="as -64" ./configure
376 ----
377
378 * Linux/Crusoe TM5800 - It is reported that recent Linux kernel thinks
379 TM5800 as i686-compatible, and compilation of Gauche fails at
380 gc where the i686's prefetch instruction is used.
381 If you want to disable this machine-dependent heuristic optimization,
382 run configure like this:
383 +
384 [source,sh]
385 ----
386 ./configure --disable-heuristic-optimization
387 ----