Home My Page Projects Code Snippets Project Openings SML/NJ
Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

SCM Repository

[smlnj] Annotation of /sml/trunk/src/smlnj-c/README
ViewVC logotype

Annotation of /sml/trunk/src/smlnj-c/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 651 - (view) (download)

1 : monnier 249 Notes on the rudimentary SML/NJ C interface rooted at this directory.
2 :    
3 :     This file provides installation instructions and details on adding
4 :     ML-callable C functions to the SML/NJ runtime system using the SML/NJ C
5 :     interface. With this interface one can call C functions that are
6 :     passed (and return) integers, floats, doubles, arrays, structs and unions,
7 :     and functions. C functions may also return arbitrary C pointers to ML which
8 :     the ML program may supply as arguments to C functions at later times.
9 :    
10 :     The file 'smlnj-c.ps' is a paper in the './doc' directory describes the
11 :     design, implementation, and operation of the C interface. It contains
12 :     examples of calling C functions from SML/NJ.
13 :    
14 :     Direct bugs, comments, questions to 'sml-nj@research.bell-labs.com'
15 :    
16 :    
17 :     1 Installation
18 :     --------------
19 :    
20 :     The interface consists of two parts: a C part in the SML/NJ runtime and
21 :     an ML part that must be explicitly loaded (into SML/NJ running with
22 :     the C-interface runtime). The C part is already contained in SML/NJ's
23 :     C runtime, but must be explicitly configured.
24 :    
25 :     1.1 Building the C-interface runtime
26 :     ------------------------------------
27 :    
28 :     The runtime system contains the C interface in the
29 :     'src/runtime/c-libs/smlnj-ccalls' directory. You must explicitly
30 :     build a runtime that supports this interface as follows:
31 :     If the file 'runtime/objs/mk.<arch>-<os>-ccalls' does not
32 :     exist, create one by:
33 :    
34 :     (0) cloning 'mk.<arch>-<os>' as 'mk.<arch>-<os>-ccalls'
35 :     (1) adding -DC_CALLS to the makefile's DEF variable
36 :     (2) making sure the makefile defines XCLIBS as:
37 :     XCLIBS = ../c-libs/smlnj-ccalls/libsmlnj-ccalls.a
38 :     (3) making sure XCLIBS is passed to 'make' for the 'all:'
39 :     target as:
40 :     XCLIBS="$(XCLIBS)"
41 :    
42 :     A sample makefile (mk.mipseb-irix5-c-calls) is attached to this file.
43 :    
44 :     Build a C-interface runtime by issuing the command
45 :     make -f mk.<arch>-<os>-ccalls
46 :     in the 'runtime/objs' directory. Move the resulting 'run.<arch>-<os>'
47 :     file to the appropriate directory (usually 'bin/.run').
48 :    
49 :     The second part of the SML/NJ-C interface is a library of ML code that
50 :     declares data types for constructing data that can be passed to C functions.
51 :     This part also provides the facilities for registering the C functions that
52 :     ML can call. This part of the interface must be loaded into the SML/NJ system
53 :     before C functions can be registered and then called.
54 :    
55 :    
56 :     1.2 Installing the SML Interface Library
57 :     ----------------------------------------
58 :    
59 :     The ML interface library resides in this directory. The important files
60 :     are: 'c-calls.sig.sml', 'c-calls.sml', and 'cc-info.<compiler>.sml'.
61 :     The 'c-calls' files are the interface. The interface is a functor
62 :     (CCalls) parameterized by info about the underlying C compiler (via
63 :     the 'cc-info.<compiler>.sml' files).
64 :    
65 :     cc-info files are SML structures that supply the C interface
66 :     (CCalls functor) with information about the C compiler.
67 :    
68 :     The shell script gen-cc-info can be used to automatically generate
69 :     a cc-info.<compiler>.sml for given compiler. Usage:
70 :     gen-cc-info cc-to-use name-for-structure >oufile
71 :     i.e.: % gen-cc-info gcc GCCInfoX86Linux >cc-info.x86-linux.sml
72 :    
73 :     (make sure you're running on the named platform when you give the
74 :     gen-cc-info command!).
75 :    
76 :     Alternately, cc-info files can be made manually. See, for example,
77 :     cc-info.defaults.sml (should be good for most 32-bit platforms)
78 :     or cc-info.mipseb-irix5.sml
79 :    
80 :     The 'sources.cm' file allows the SML/NJ Compilation Manager (CM) to
81 :     build the interface. At an sml-cm prompt, do a 'CM.make()'.
82 :    
83 :     Alternately, the file 'load.sml' shows how to put it all together.
84 :     "Using" it at the top level creates an instance on an interface
85 :     (and utility functions used by that interface).
86 :    
87 :    
88 :     2 Usage
89 :     -------
90 :    
91 :     2.1 Adding C Functions
92 :     ----------------------
93 :    
94 :     Installation of the runtime as described above links in the C functions
95 :     in 'src/runtime/c-libs/c-calls/cutil.c'. The C functions defined
96 :     in 'cutil.c' are bound to names that ML programs can find through
97 :     the file 'cutil-cfuns.c'. Each function imported to SML/NJ from
98 :     'cutil.c' has a line such as:
99 :    
100 :     C_CALLS_CFUNC("ptos", ptos, char *, (void *))
101 :    
102 :     in 'cutil-cfuns.h'. This line registers the C function 'ptos'
103 :     with name 'ptos', return type 'int', and arg type(s) 'char *'
104 :     with the SML-NJ runtime. A C_CALLS_CFUNC line must exist for every
105 :     user C function callable from ML.
106 :    
107 :     The file 'cutil-cfuns.h' must be included by the file 'cfun-list.h'.
108 :     When adding a set of related functions, it is useful to place their
109 :     C_CALLS_FUNC entries in a '*-cfuns.h' file and to then include this
110 :     file from 'cfun-list.h'. For example, to add a new file 'f.c' of C
111 :     functions, create a file 'f-cfuns.h' with C_CALLS_CFUNC definitions for
112 :     all functions exported by 'f.c'. Add a '#include "f-cfuns.h"' to
113 :     'cfun-list.h'. Edit 'makefile' to build 'f.o', i.e. add 'f.o' to the
114 :     makefile's C_CALLS_OBJS variable and add a rule for 'f.o'
115 :     (see, for example, the rule for 'cutil.o').
116 :    
117 :    
118 :     2.2 Linking in C libraries
119 :     --------------------------
120 :    
121 :     Adding a C function may require linking against some C library
122 :     not currently linked against by the SML-NJ runtime. These libraries
123 :     can be linked against as follows.
124 :    
125 :     Edit 'src/runtime/objs/mk.<arch>-<os>-calls' and alter the LD_LIBS variable
126 :     to include the desired libraries. For example,
127 :    
128 :     LD_LIBS = -lX11 -lm -lmalloc
129 :    
130 :     links in the malloc, math and X11 libs.
131 :    
132 :    
133 :     2.3 Calling C Functions from ML
134 :     -------------------------------
135 :    
136 :     Refer to the paper 'smlnj-c.ps' for instructions on registering and
137 :     calling C functions that have been added to the runtime system.
138 :    
139 :     The file 'cutil.sml' in this directory provides a few examples.
140 :    
141 :    
142 :     3.0 Sample "mk.<arch>-<os>-ccalls" file.
143 :     ----------------------------------------
144 :    
145 :     # mk.mipseb-irix5-ccalls
146 :     #
147 :    
148 :     SHELL = /bin/sh
149 :    
150 :     CC = cc -xansi -D__STDC__
151 :     CPP = /usr/lib/acpp
152 :     CFLAGS = -O
153 :     AS = /bin/as -nocpp
154 :     RANLIB = ar ts
155 :    
156 :     #XOBJS = xmonitor.o
157 :     #LD_LIBS = -lX11_s -lmalloc
158 :     #BASE_DEFS = -DHEAP_MONITOR
159 :     XOBJS =
160 :     XLIBS =
161 :     XCLIBS = ../c-libs/smlnj-ccalls/libsmlnj-ccalls.a
162 :     LD_LIBS = -lmalloc
163 :     BASE_DEFS =
164 :     DEFS = $(BASE_DEFS) -DHOST_MIPS -DTARGET_MIPS -DOPSYS_UNIX -DOPSYS_IRIX5 -DCALLEESAVE=3 -DC_CALLS
165 :     TARGET = MIPS
166 :     VERSION = v-mipseb-irix5
167 :     RUNTIME = run.mipseb-irix5
168 :    
169 :     all:
170 :     (make RUNTIME="$(RUNTIME)" VERSION="$(VERSION)" CC="$(CC)" CPP="$(CPP)" CFLAGS="$(CFLAGS)" AS="$(AS)" RANLIB="$(RANLIB)" TARGET=$(TARGET) DEFS="$(DEFS)" XOBJS="$(XOBJS)" XLIBS="$(XLIBS)" LD_LIBS="$(LD_LIBS)" XCLIBS="$(XCLIBS)" $(RUNTIME))
171 :    

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0