File: QUICKSTART.xml

package info (click to toggle)
findlib 1.8.1-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 1,868 kB
  • sloc: ml: 6,006; xml: 3,085; sh: 1,490; makefile: 378
file content (288 lines) | stat: -rw-r--r-- 8,301 bytes parent folder | download | duplicates (8)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE readme SYSTEM "readme.dtd" [

<!ENTITY % common SYSTEM "common.xml">
%common;

<!-- Special HTML config: -->
<!ENTITY % readme:html:up '<a href="../..">up</a>'>

<!ENTITY % config SYSTEM "config.xml">
%config;

]>

<readme title="QUICKSTART - The most important ways to use findlib">
  <sect1>
    <title>Intro</title>
    <p>See the file INSTALL for instructions how to build and install
findlib.</p>
  </sect1>

  <sect1>
    <title>Findlib and the toploop</title> 

<p>For a number of platforms, O'Caml can load bytecode-compiled
libraries dynamically. For these platforms, findlib is very simple to
use as explained in the following. For other platforms, see the paragraph
below about "custom toploops".</p>

    <p>After the toploop has been started, it is possible to load the special
findlib support:<footnote>In previous versions, #use "findlib" loaded the
library. However, this caused a name conflict for a certain type of
installation. Because of this, the name of the loader script has been changed
to "topfind", but "findlib", and "ocamlfind" (Debian) are also available
for backwards compatibility.</footnote>

<code>
$ ocaml
        Objective Caml version 3.07

# #use "topfind";;
Findlib has been successfully loaded. Additional directives:
  #require "package";;      to load a package
  #list;;                   to list the available packages
  #camlp4o;;                to load camlp4 (standard syntax)
  #camlp4r;;                to load camlp4 (revised syntax)
  #predicates "p,q,...";;   to set these predicates
  Topfind.reset();;         to force that packages will be reloaded
  #thread;;                 to enable threads

- : unit = ()
</code>

You can now list the available packages:

<code>
# #list;;
bigarray            (version: [distributed with Ocaml])
camlp4              (version: Camlp4 version 3.03 ALPHA)
dbm                 (version: [distributed with Ocaml])
dynlink             (version: [distributed with Ocaml])
findlib             (version: 0.6)
graphics            (version: [distributed with Ocaml])
labltk              (version: [distributed with Ocaml])
netstring           (version: 0.10)
num                 (version: [distributed with Ocaml])
stdlib              (version: [distributed with Ocaml])
str                 (version: [distributed with Ocaml])
threads             (version: [distributed with Ocaml])
unix                (version: [distributed with Ocaml])
xstrp4              (version: 1.1)
</code>

and load packages by simply typing:

<code>
# #require "netstring";;
Loading /opt/ocaml/lib/unix.cma
Loading /opt/ocaml/lib/str.cma
Loading /opt/ocaml/site-lib/netstring/netstring.cma
Loading /opt/ocaml/site-lib/netstring/netstring_top.cmo
</code>

Findlib takes care to load packages that are required by loaded packages
first. For example, "netstring" uses "unix" and "str" internally, but you
do not need to load them because findlib does it for you. In this example
you can also see that findlib loads netstring_top.cmo containing printers
for the toploop.</p>

    <p>You can also enable the Camlp4 parsers by simply typing

<code>
# #camlp4o;;
Loading /opt/ocaml-3.03a/lib/camlp4/camlp4o.cma
        Camlp4 Parsing version 3.03 ALPHA
</code>

for the standard syntax or

<code>
# #camlp4r;;
Loading /opt/ocaml-3.03a/lib/camlp4/camlp4r.cma
        Camlp4 Parsing version 3.03 ALPHA
</code>

for the revised syntax. (But you cannot switch between the syntaxes.)
</p>
  </sect1>

  <sect1>
    <title>Custom Toploops</title>

    <p>For some platforms, O'Caml does not implement loading external
libraries (e.g. Cygwin). One has to create a so-called custom toploop
that statically links with these libraries. Example:

<code>
$ ocamlfind ocamlmktop -o mytop -package findlib,unix -linkpkg
$ ./mytop
        Objective Caml version 3.07
 
# #use "topfind";;
Findlib has been successfully loaded. Additional directives:
  #require "package";;      to load a package
  #list;;                   to list the available packages
  #camlp4o;;                to load camlp4 (standard syntax)
  #camlp4r;;                to load camlp4 (revised syntax)
  #predicates "p,q,...";;   to set these predicates
  Topfind.reset();;         to force that packages will be reloaded
  #thread;;                 to enable threads

- : unit = ()
</code>

Now "#require" works for all libraries referring to the special "unix"
functions.
</p>
  </sect1>

  <sect1>
    <title>Findlib and scripts</title>

    <p>The #require directive can also be used in scripts. Example:

<code>
#use "topfind";;
#require "netstring";;

open Cgi;;
...
</code>

This makes it possible to write scripts that do not contain #directory
directives that are specific for certain installations.</p>

    <p>For Unix environments, you can start scripts directly if you
apply the following trick:

<code>
#! /bin/sh
# (*
exec ocaml "$0" "$@"
*) use "topfind";;
#require "netstring";;

open Cgi;;
...
</code>

This works wherever O'Caml is installed.</p>
  </sect1>

  <sect1>
    <title>Compiling programs</title>

    <p>Assumed you want to compile a program that uses the Netstring package.
Do it the following way:

<code>
$ ocamlfind ocamlc -package netstring -c myprogram.ml
</code>

This way you do not need to add "-I" options to locate Netstring.</p>

    <p>If you want to create an executable, do not forget to add the
-linkpkg switch:

<code>
$ ocamlfind ocamlc -o myprogram -package netstring -linkpkg myprogram.cmo
</code>

This switch causes that the mentioned packages are added to the resulting
executable.</p>

    <p>If you want to include several packages, you can either add several
"-package" options, or you can enumerate the packages separated by commas:
-package netstring,labltk.</p>
  </sect1>

  <sect1>
    <title>Camlp4</title>

    <p>If you add a -syntax option, the compiler will be told to parse the
source file using camlp4:

<code>
$ ocamlfind ocamlc -package netstring -syntax camlp4o -c myprogram.ml
</code>

Use -syntax camlp4o for the standard syntax or -syntax camlp4r for the
revised syntax.</p>

    <p>Additionally, you can mention packages that add new syntax features.
The package xstrp4 is an example of this:

<code>
$ ocamlfind ocamlc -package xstrp4,netstring -syntax camlp4o -c myprogram.ml
</code>

Now you can use the $ notation that is implemented by xstrp4 in the
source file myprogram.ml.</p>

    <p>Note that you can also invoke ocamldep from ocamlfind:

<code>
$ ocamlfind ocamldep -package xstrp4 -syntax camlp4o *.ml *.mli &gt;.depend
</code>

This enables the syntax extensions, too.</p>
  </sect1>

  <sect1>
    <title>ocamlbrowser</title>
    <p>Since findlib-0.7, it is also possible to start ocamlbrowser from
ocamlfind. For example,

<code>
$ ocamlfind browser -package xstrp4
</code>

adds the correct path specification such that the modules contained in the
package xstrp4 are also displayed. With

<code>
$ ocamlfind browser -all
</code>

all package are added to the path spec.
</p>
  </sect1>

  <sect1>
    <title>The Makefile wizard</title>
    <p>There is a wizard that makes it very easy to write Makefiles. Call the
wizard by
<code>
$ ocamlfind findlib/make_wizard
</code>
(the wizard requires that the labltk library is available). A new window
pops up, and by very few clicks you can describe your own library. Finally,
a Makefile is written.
</p>
  </sect1>

  <sect1>
    <title>There is no magic!</title>

    <p>Findlib is neither a patch of O'Caml nor uses it internal features of
the O'Caml programming environment. It is only a convention to install
software components in filesystem hierarchies, a library interpreting 
this convention, and some frontend applications making the library useable for
you.</p>

    <p>One important consequence is that you can only refer to those
software components that have previously been installed in a way findlib
understands. This convention is beyond the scope of this QUICKSTART guide,
see the reference manual for details. You can always check whether findlib
accepts a component as "findlib package" by the command

<code>
$ ocamlfind list
</code>

(this is the same as the #list directive in the toploop). If the package
occurs in the list, it is found, otherwise not.</p>
  </sect1>
</readme>