source: README

Last change on this file was 941:bf17a6ac786c, checked in by rtoy, 12 years ago

Fix typo.

File size: 10.1 KB
Line 
1Welcome to f2cl - a Fortran to Common Lisp Translator
2
3Contained in this directory are source code files and some documentation.
4The translator is written in Common Lisp making installation simple.
5
6Installation
7------------
8
9If this has been extracted as a part of CLOCC, the way to build f2cl
10is to simply run "make system" from a shell, as is usual with CLOCC
11packages.
12
13A second method is to use defsystem from CLOCC.  Then load
14f2cl.system, and then finally run (mk:oos "f2cl" :compile). 
15
16A third method is to use asdf.  You can load f2cl.asd and run
17(asdf:oos 'asdf:load-op :f2cl).
18
19Finally, a fourth method, if you have none of the above, is to
20manually run everything as follows:
21
221. Start your favorite Common Lisp implementation use the function
23   "compile-file" to compile each of the source files:
24
25                f2cl0.l
26                f2cl1.l
27                f2cl2.l
28                f2cl3.l
29                f2cl4.l
30                f2cl5.l
31                f2cl6.l
32                f2cl7.l
33                macros.l
34
352. Load up all of the files
36
37           (load "f2cl0.l")
38           (load "f2cl1.l")
39           (load "f2cl2.l")
40           (load "f2cl3.l")
41           (load "f2cl4.l")
42           (load "f2cl5.l")
43           (load "f2cl6.l")
44           (load "f2cl7.l")
45           (load "macros.l")
46
47   to load all the compiled files.
48
49
50Usage
51-----
52
53Converting Fortran Code
54-----------------------
55To use f2cl:
56
57(f2cl:f2cl "<path>/fortran.f")
58
59will convert the file "<path>/fortran.f" to Lisp code and places the
60result in the file "<path>/fortran.lisp".
61
62Alternatively,
63
64(f2cl:f2cl-compile "<path>/fortran.f")
65
66will also run compile-file on the Lisp file so you can load it
67directly into your lisp.
68
69
70For those anxious to use the translator without studying the documentation
71here is a short list of restrictions that may result in obscure errors:
72 - input code is assumed to be valid Fortran 77
73 - no tabs are permitted in the source,
74 - $comments should only be turned on if the Fortran code has comments
75   exclusively within subroutines,
76 - linebreaks must occur within whitespace,
77 - spaces are required to separate symbols.
78Note also that an intermediate file called "prep.tmp" is produced by the
79preprocessing stage of the translation.
80
81Options
82-------
83
84These are the options available to f2cl:f2cl and f2cl:f2cl-compile
85
86:OUTPUT-FILE             
87        File to contain Lisp code
88
89:VERBOSE               
90        Verbose output. Default = NIL.  Mostly for debugging.
91
92:PRUNE-LABELS           
93        Prune unused labels. Default = NIL.
94
95:INCLUDE-COMMENTS       
96        Include Fortran comments in the Lisp output.
97        Default = NIL
98
99:AUTO-SAVE             
100        Variables in DATA statements are automatically SAVE'd. Default
101        = T.
102
103:RELAXED-ARRAY-DECLS   
104        Declarations of array sizes are relaxed in formal
105        parameters to functions. That is, any array
106        length declarations (except lower limits) are
107        ignored if possible, like old Fortran used
108        to. Default = T.
109
110:COERCE-ASSIGNS
111        If T or :ALWAYS, all assignment statements automatically
112        coerce the RHS to the appropriate type for the assignment.  If
113        NIL or :NEVER, coercion never happens.  If :AS-NEEDED, f2cl
114        applies coercion if it thinks it is needed.  Default =
115        :AS-NEEDED.
116
117:EXTENSION               
118        The extension to use for the output file, if needed.  Defaults
119        to *DEFAULT-LISP-EXTENSION* or "lisp".
120
121:KEEP-TEMP-FILE
122        If T, the temporary file is not deleted.  This is mostly for
123        debugging f2cl. Default = NIL.
124
125:ARRAY-TYPE
126        The type of array f2cl should use.  Should be :simple-array or
127        :array.  For some compilers, there can be significant speed up
128        if the array can be declared as simple-arrays.  But this is
129        incompatible with array-slicing, so care must be used if you
130        choose :simple-array. Default = :array.
131
132:ARRAY-SLICING
133        When non-NIL, f2cl assumes that, whenever we do an array
134        reference in a call to a subroutine or function, we are really
135        passing a subarray to the routine instead of just the single
136        value, unless f2cl knows the function takes a scalar arg that
137        is not modified.  Default = T.
138
139:PACKAGE
140        A string or symbol specifying what package the resulting code
141        should be in. (Basically puts a (in-package <p>) at the top.)
142        Default is COMMON-LISP-USER.
143
144:DECLAIM
145        Declaim compilation options (Basically puts a (declaim
146        <declaim>) at the top.)  Default is none.
147
148:DECLARE-COMMON
149        When non-NIL, any structures definitions for common blocks are
150        defined when converting this file. Otherwise, the structures
151        for the common blocks are expected to be defined elsewhere.
152        This should be used only once for one subprogram that will be
153        used to define the common block.  See below for more
154        information. Default is NIL.
155
156:FLOAT-FORMAT           
157        Float format to use when printing the result.  Default is
158        *READ-DEFAULT-FLOAT-FORMAT*
159
160:COMMON-AS-ARRAY
161        Instead of defining a common block as a structure with the
162        same slot names as variables in the common block, the common
163        block is defined as a set of arrays.  The actual common block
164        variables are defined as offsets into these arrays.  For more
165        information see below.  This mimics the memory layout of how
166        Fortran treats common blocks.  Default = NIL.
167
168Using Converted Code
169--------------------
170
171Once you've converted the code, you do not need to load up all of f2cl
172to use the converted code.  In fact, you only need f2cl0.l and
173macros.l to define the necessary packages and functions used by the
174converted code.  Actually, you really only need the defpackage for
175f2cl-lib in f2cl0.l.
176
177Issues
178------
179
180For a more detailed list of issues and notes, see src/NOTES.
181
182We highlight just a few issues here.
183
184o Block data statements.
185
186    In Fortran, block data statments are used to initialize common
187    blocks.  Since Fortran executables are loaded and run just once,
188    this is not a problem.  However, in Lisp, this might not be true,
189    and you may want to run the main program many times.  Thus, it is
190    up to you to run the block data initializer at the right time, as
191    needed.  f2cl cannot know when and where to call the initializer.
192
193o Common blocks. 
194
195    F2cl converts common blocks to structures.  However, common blocks
196    may be referenced in several different files, so the user must
197    tell f2cl when to define the structure.  Use the :declare-common
198    parameter to tell f2cl to define the structure. This should be
199    done exactly once for each common block that is defined.  This
200    should also be done for the first file that is compiled and
201    loaded, so that subsequent files know about the definition.
202
203    In addition, there is another option, :common-as-array.  This
204    changes how f2cl handles common blocks.   A rather common use of
205    common blocks has the same common block using different variable
206    names.  For example, one routine might have
207
208        COMMON /foo/ a(10), b, i(4)
209
210    and another might say
211
212        COMMON /foo/ b(9), c, d, j(2), k(2)
213
214    In Fortran, this is perfectly acceptable.  Normally, f2cl expects
215    all common blocks to use the same variable names, and then f2cl
216    creates a structure for the common block using the variable names
217    as the names of the slots.  However, for a case like the above,
218    f2cl gets confused.  Hence, :common-as-array.  We treat the common
219    block as an array of memory.  So this gets converted into a
220    structure somewhat like
221
222        (defstruct foo
223          (part-0 (make-array 11 :element-type 'real))
224          (part-1 (make-array 4 :element-type 'integer4)))
225
226    (In a more general case, we group all contiguous variables of the
227    same type into one array.  f2cl and Lisp cannot handle the case
228    where a real and integer value are allocated to the same piece of
229    memory.)
230
231    Then in the individual routines, symbol-macrolets are used to
232    create accessors for the various definitions.  Hence, for the
233    second version, we would do something like
234
235          (symbol-macrolet
236            (b (make-array 9 :displaced-to
237                           (foo-part-0 *foo*)
238                           :diplaced-offset 0))
239            (c (aref (foo-part-0 *foo*) 9))
240            (d (aref (foo-part-0 *foo*) 10))
241            (j (make-array 2 :displaced-to
242                           (foo-part-1 *foo*)
243                           :displaced-offset 0))
244            (k (make-array 2 :displaced-to
245                           (foo-part-1 *foo*)
246                           :displaced-offset 2))
247            ...)
248
249    Thus, we access the right parts of the common block, independent
250    of the name.  Note that this has a performance impact since we
251    used displaced arrays.
252 
253
254
255o Conversion order.
256
257    While not necessary, f2cl can do a significantly better job in
258    generating code if the functions are compiled in the correct
259    order.  This means any function, F, that is called by another
260    function, G,  should compiled first.  In this way, f2cl can
261    determine the calling conventions for F, and generate the
262    appropriate call for F in G.  This is important if F takes an
263    array argument and G passes a slice of an array to F, or
264    conversely if F takes a simple variable, and G calls F with an
265    array reference. 
266
267    If this is not done, the user may have to modify either the
268    Fortran code or the resulting Lisp code to pass arguments
269    correctly. 
270
271    F2cl cannot always determine whether a slice of an array should be
272    used or just the single element.
273
274See also the file src/NOTES which contains a change log.  But there
275are also various notes about about restrictions and enhancements on
276various features supported by f2cl.
277
278
279Acknowledgments:
280
281The translator was written by Kevin Broughan and Diane Koorey Willcock
282at the University of Waikato. Reports should be sent to
283kab@waikato.ac.nz and should include examples of Fortran code which
284fails to translate or which translates incorrectly.
285
286Major changes have be written by Raymond Toy and the entire translator
287is now part of CLOCC, with permission from Kevin Broughan.  Send bug
288reports and other comments to http://clocc.sourceforge.net.
289
290The code is also placed under the GPL, by permission of Kevin
291Broughan.  The exception is macros.l which is released under the LGPL
292so that it can be incorporated into other packages.
Note: See TracBrowser for help on using the repository browser.