source: project/wiki/man/5/faq @ 34716

Last change on this file since 34716 was 34716, checked in by sjamaan, 2 years ago

man/5: Replace (use) by (import) in examples, remove some obsolete bits about "use"

File size: 29.4 KB
Line 
1[[toc:]]
2[[tags:faq manual]]
3
4== FAQ
5
6This is the list of Frequently Asked Questions about CHICKEN Scheme.
7If you have a question not answered here, feel free to post to the chicken-users mailing list;
8if you consider your question general enough, feel free to add it to this list.
9
10=== General
11
12==== Why yet another Scheme implementation?
13
14Since Scheme is a relatively simple language, a large number of implementations exist and
15each has its specific advantages and disadvantages. Some are fast, some provide a rich
16programming environment. Some are free, others are tailored to specific domains, and so on. The reasons
17for the existence of CHICKEN are:
18
19* CHICKEN is portable because it generates C code that runs on a large number of platforms.
20
21* CHICKEN is extensible, since its code generation scheme and runtime system/garbage collector fits neatly into a C environment.
22
23* CHICKEN is free and can be freely distributed, including its source code.
24
25* CHICKEN offers better performance than nearly all interpreter based implementations, but still provides full Scheme semantics.
26
27* As far as we know, CHICKEN is the first implementation of Scheme that uses Henry Baker's [[http://home.pipeline.com/~hbaker1/CheneyMTA.html|Cheney on the M.T.A]] concept.
28
29==== What should I do if I find a bug?
30
31Fill a ticket at [[http://bugs.call-cc.org|bugs.call-cc.org]] with
32some hints about the problem, like version/build of the compiler,
33platform, system configuration, code that causes the bug, etc.
34
35
36=== Specific
37
38==== Why are values defined with {{define-foreign-variable}} or {{define-constant}} or {{define-inline}} not seen outside of the containing source file?
39
40Accesses to foreign variables are translated directly into C constructs that access the variable,
41so the Scheme name given to that variable does only exist during compile-time.
42The same goes for constant- and inline-definitions: The name is only there to tell the compiler
43that this reference is to be replaced with the actual value.
44
45==== How does {{cond-expand}} know which features are registered in used units?
46
47Each unit used via {{(declare (uses ...))}} is registered as a feature and
48so a symbol with the unit-name can be tested by {{cond-expand}} during macro-expansion-time.
49Features registered using the {{register-feature!}} procedure are only
50available during run-time of the compiled file. You can use the {{eval-when}} form
51to register features at compile time.
52
53==== Why are constants defined by {{define-constant}} not honoured in {{case}} constructs?
54
55{{case}} expands into a cascaded {{if}} expression, where the first item in each arm
56is treated as a quoted list. So the {{case}} macro can not infer whether
57a symbol is to be treated as a constant-name (defined via {{define-constant}}) or
58a literal symbol.
59
60
61==== How can I enable case sensitive reading/writing in user code?
62
63To enable the {{read}} procedure to read symbols and identifiers case sensitive, you can set the
64parameter {{case-sensitivity}} to {{#t}}.
65
66
67==== Why doesn't CHICKEN support the full numeric tower by default?
68
69As of Chicken 5, it does!  The {{numbers}} egg is no longer necessary
70or supported.
71
72Note that unlike some other Schemes, Chicken does not support complex
73numbers with mixed exactness.  If either argument to {{make-rectangular}}
74is inexact, the resulting complex number will be inexact in both its
75real and imaginary parts.  Either behavior is allowed by the various
76Scheme standards.
77
78==== Does CHICKEN support native threads?
79
80Native threads are not supported for two reasons. One, the runtime
81system is not reentrant.  Two, concurrency implemented properly would
82require mandatory locking of every object that could be potentially
83shared between two threads. The garbage-collection algorithm would
84then become much more complex and inefficient, since the location of
85every object has to be accessed via a thread synchronization
86protocol. Such a design would make native threads in CHICKEN
87essentially equivalent to Unix processes and shared memory.
88
89For a different approach to concurrency, please see the
90[[/egg/mpi|mpi]] or
91[[/egg/concurrent-native-callbacks|concurrent-native-callbacks]] egg.
92
93[[http://www.stylewarning.com/blog/about|Robert Smith]] has put
94[[http://www.stylewarning.com/blog/bounties|a bounty]] on a
95release-quality implementation of native threads.
96
97==== Does CHICKEN support Unicode strings?
98
99The system does not directly support Unicode, but there is an extension for UTF-8 strings: [[/egg/utf8|utf8]].
100
101=== Why are `dynamic-wind' thunks not executed when a thread signals an error?
102
103Here is what Marc Feeley, the author of [[http://srfi.schemers.org/srfi-18|SRFI-18]] has to
104say about this subject:
105
106    >No the default exception handler shouldn't invoke the after
107    > thunks of the current continuation.  That's because the
108    > exception handler doesn't "continue" at the initial
109    > continuation of that thread.  Here are the relevant words of
110    > SRFI 18:
111   
112    >
113    >  Moreover, in this dynamic environment the exception handler
114    >  is bound to the "initial exception handler" which is a unary
115    >  procedure which causes the (then) current thread to store in
116    >  its end-exception field an "uncaught exception" object whose
117    >  "reason" is the argument of the handler, abandon all mutexes
118    >  it owns, and finally terminate.
119    >
120   
121    >The rationale is that, when an uncaught exception occurs in a
122    >thread the thread is in bad shape and things have gone
123    >sufficiently wrong that there is no universally acceptable way to
124    >continue execution.  Executing after thunks could require a
125    >whole lot of processing that the thread is not in a shape to do.
126    >So the safe thing is to terminate the thread.  If the programmer
127    >knows how to recover from an exception, then he can capture the
128    >continuation early on, and install an exception handler which
129    >invokes the continuation.  When the continuation is invoked the
130    >after thunks will execute.
131
132
133=== Platform specific
134
135==== How do I generate a DLL under MS Windows (tm) ?
136
137Use {{csc}} in combination with the {{-dll}} option:
138
139{{C:\> csc foo.scm -dll}}
140
141==== How do I generate a GUI application under Windows(tm)?
142
143Invoke {{csc}} with the {{-gui}} option.  In GUI-mode, the runtime
144system displays error messages in a message box and does some
145rudimentary command-line parsing.
146
147==== Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space.
148
149It seems that the Microsoft C compiler can only handle files up to a certain size, and it doesn't utilize virtual memory as
150well as the GNU C compiler, for example. Try closing running applications. If that fails, try to break up the Scheme code
151into several library units.
152
153==== When I run {{csi}} inside an emacs buffer under Windows, nothing happens.
154
155Invoke {{csi}} with the {{-:c}} runtime option. Under Windows the interpreter thinks it
156is not running under control of a terminal and doesn't print the prompt and does not flush the output stream properly.
157
158==== On Windows, {{csc.exe}} seems to be doing something wrong.
159
160The Windows development tools include a C# compiler with the same name. Either invoke {{csc.exe}} with a full
161pathname, or put the directory where you installed CHICKEN in front of the MS development tool path in the {{PATH}}
162environment variable.
163
164==== On Windows source and/or output filenames with embedded whitespace are not found.
165
166There is no current workaround. Do not use filenames with embedded whitespace for code. However, command
167names with embedded whitespace will work correctly.
168=== Customization
169
170
171==== How do I run custom startup code before the runtime-system is invoked?
172
173When you invoke the C compiler for your translated Scheme source program, add the C compiler option
174{{-DC_EMBEDDED}}, or pass {{-embedded}} to the {{csc}}
175driver program, so no entry-point function will be generated ({{main()}}).
176When your are finished with your startup processing, invoke:
177
178<enscript highlight=c>
179CHICKEN_main(argc, argv, C_toplevel);
180</enscript>
181
182where {{C_toplevel}} is the entry-point into the compiled Scheme code. You
183should add the following  declarations at the head of your code:
184
185<enscript highlight=c>
186#include "chicken.h"
187extern void C_toplevel(C_word,C_word,C_word) C_noret;
188</enscript>
189
190==== How can I add compiled user passes?
191
192To add a compiled user pass instead of an interpreted one, create a library unit and recompile
193the main unit of the compiler (in the file {{chicken.scm}}) with an additional {{uses}}
194declaration. Then link all compiler modules and your (compiled) extension to create a new version of
195the compiler, like this (assuming all sources are in the
196current directory):
197
198<enscript highlight=scheme>
199  % cat userpass.scm
200  ;;;; userpass.scm - My very own compiler pass
201
202  (declare (unit userpass))
203
204  ;; Perhaps more user passes/extensions are added:
205  (let ([old (user-pass)])
206    (user-pass
207      (lambda (x)
208        (let ([x2 (do-something-with x)])
209           (if old
210               (old x2)
211               x2) ) ) ) )
212</enscript>
213
214 % csc -c -x userpass.scm
215 % csc chicken.scm -c -o chicken-extended.o -uses userpass
216 % gcc chicken-extended.o support.o easyffi.o compiler.o optimizer.o batch-driver.o c-platform.o \
217 c-backend.o userpass.o `csc -ldflags -libs` -o chicken-extended
218
219On platforms that support it (Linux ELF, Solaris, Windows + VC++), compiled code can be loaded via {{-extend}}
220just like source files (see {{load}} in the User's Manual).
221
222
223=== Macros
224
225==== Where is {{define-macro}}?
226
227In CHICKEN 4 and 5, the macro-expansion subsystem is now hygienic where old Lisp-style low-level macros
228are not available anymore. {{define-syntax}} can define hygienic macros using {{syntax-rules}}
229or low-level macros with user-controlled hygienic with ''explicit renaming'' macros. Translating
230old-style macros into ER-macros isn't that hard, see [[Macros]] for more information.
231
232==== Why are low-level macros defined with {{define-syntax}} complaining about unbound variables?
233
234Macro bodies that are defined and used in a compiled source-file are
235evaluated during compilation and so have no access to anything created with {{define}}. Use {{define-for-syntax}} instead.
236
237==== Why isn't {{load}} properly loading my library of macros?
238
239During compile-time, macros are only available in the source file in which they are defined. Files included via {{include}} are considered part of the containing file.
240
241=== Warnings and errors
242
243==== Why does my program crash when I use callback functions (from Scheme to C and back to Scheme again)?
244
245There are two reasons why code involving callbacks can crash out of no apparent reason:
246
247# It is important to use {{foreign-safe-lambda/foreign-safe-lambda*}} for the C code that is to call back into Scheme. If this is not done than sooner or later the available stack space will be exhausted.
248
249# If the C code uses a large amount of stack storage, or if Scheme-to-C-to-Scheme calls are nested deeply, then the available nursery space on the stack will run low. To avoid this it might be advisable to run the compiled code with a larger nursery setting, i.e. run the code with {{-:s...}} and a larger value than the default (for example {{-:s300k}}), or use the {{-nursery}} compiler option.  Note that this can decrease runtime performance on some platforms.
250
251==== Why does the linker complain about a missing function {{_C_..._toplevel}}?
252
253This message indicates that your program uses a library-unit, but that the
254object-file or library was not supplied to the linker. If you have the unit
255{{foo}}, which is contained in {{foo.o}} than you have to supply it to the
256linker like this (assuming a GCC environment):
257
258{{% csc program.scm foo.o -o program}}
259
260==== Why does the linker complain about a missing function {{_C_toplevel}}?
261
262This means you have compiled a library unit as an application. When a unit-declaration (as in {{(declare (unit ...))}})
263is given, then this file has a specially named toplevel entry procedure. Just remove the declaration,
264or compile this file to an object-module and link it to your application code.
265
266==== Why does my program crash when I compile a file with {{-unsafe}} or unsafe declarations?
267
268The compiler option {{-unsafe}} or the declaration {{(declare (unsafe))}} disable
269certain safety-checks to improve performance, so code that would normally
270trigger an error will work unexpectedly or even crash the running application.
271It is advisable to develop and debug a program in safe mode (without unsafe
272declarations) and use this feature only if the application works properly.
273
274==== Why don't toplevel-continuations captured in interpreted code work?
275
276Consider the following piece of code:
277
278<enscript highlight=scheme> 
279(define k (call-with-current-continuation (lambda (k) k)))
280(k k)
281</enscript>
282
283When compiled, this will loop endlessly. But when interpreted, {{(k k)}} will return
284to the read-eval-print loop! This happens because the continuation captured will eventually read the
285next toplevel expression from the standard-input (or an input-file if loading from a file). At the moment
286{{k}} was defined, the next expression was {{(k k)}}. But when {{k}}
287is invoked, the next expression will be whatever follows after {{(k k)}}.
288In other words, invoking a captured continuation will not rewind the file-position of the input source.
289A solution is to wrap the whole code into a {{(begin ...)}} expression, so all toplevel
290expressions will be loaded together.
291
292==== Why does {{define-reader-ctor}} not work in my compiled program?
293
294The following piece of code does not work as expected:
295
296<enscript highlight=scheme>
297 (eval-when (compile)
298 (define-reader-ctor 'integer->char integer->char) )
299 (print #,(integer->char 33))
300</enscript>
301
302The problem is that the compiler reads the complete source-file before doing any processing on it,
303so the sharp-comma form is encountered before the reader-ctor is defined. A possible solution is to include
304the file containing the sharp-comma form, like this:
305
306<enscript highlight=scheme>
307 (eval-when (compile)
308 (define-reader-ctor 'integer->char integer->char) )
309 
310 (include "other-file")
311</enscript>
312
313<enscript highlight=scheme>
314 ;;; other-file.scm:
315 (print #,(integer->char 33))
316</enscript>
317
318==== Why do built-in units, such as srfi-4 and posix fail to load?
319
320When you try to {{import}} a built-in unit such as {{posix}} (which defines among other things, the {{(chicken posix)}} module), you may get the following error:
321
322<enscript highlight=scheme>
323 #;1> (import (chicken posix))
324 ; loading library posix ...
325 Error: (load-library) unable to load library
326 posix
327 "dlopen(libchicken.dylib, 9): image not found"                ;; on a Mac
328 "libchicken.so: cannot open shared object file: No such file or directory"  ;; Linux
329</enscript>
330
331Another symptom is that {{(require 'posix)}} will silently fail.
332
333This typically happens because the CHICKEN libraries have been installed in a non-standard location, such as your home directory.  The workaround is to explicitly tell the dynamic linker where to look for your libraries:
334
335 export DYLD_LIBRARY_PATH=~/scheme/chicken/lib:$DYLD_LIBRARY_PATH ;; Mac
336 export LD_LIBRARY_PATH=~/scheme/chicken/lib:$LD_LIBRARY_PATH    ;; Linux
337
338==== How can I increase the size of the trace shown when runtime errors are detected?
339
340When a runtime error is detected, CHICKEN will print the last entries from the trace of functions called
341(unless your executable was compiled with the {{-no-trace}} option.
342By default, only 16 entries will be shown.
343To increase this number pass the {{-:aN}} parameter to your executable.
344
345
346=== Optimizations
347
348==== How can I obtain smaller executables?
349
350If you don't need {{eval}} or the stuff in the {{extras}} library unit,
351you can just use the {{library}} unit:
352
353<enscript highlight=scheme>
354        (declare (uses library))
355        (display "Hello, world!\n")
356</enscript>
357
358(Don't forget to compile with the {{-explicit-use}} option)
359Compiled with Visual C++ this generates an executable of around 240 kilobytes.
360It is theoretically possible to compile something without the library, but
361a program would have to implement quite a lot of support code on its own.
362
363==== How can I obtain faster executables?
364
365There are a number of declaration specifiers that should be used to speed up
366compiled files: declaring {{(standard-bindings)}} is mandatory, since this enables
367most optimizations. Even if some standard procedures should be redefined, you can
368list untouched bindings in the declaration.
369Declaring {{(extended-bindings)}} lets the compiler choose faster versions of certain
370internal library functions. This might give another speedup. You can also use the
371the {{usual-integrations}} declaration, which is identical to declaring
372{{standard-bindings}} and {{extended-bindings}}
373(note that {{usual-integrations}} is set by default).
374Declaring {{(block)}} tells the compiler that global procedures are not changed
375outside the current compilation unit, this gives the compiler some more
376opportunities for optimization.
377If no floating point arithmetic is required, then declaring {{(number-type fixnum)}}
378can give a big performance improvement, because the compiler can now inline
379most arithmetic operations.
380Declaring {{(unsafe)}} will switch off most safety checks.
381If threads are not used, you can declare {{(disable-interrupts)}}.
382You should always use maximum optimizations settings for your C compiler.
383Good GCC compiler options on Pentium (and compatible) hardware are:
384{{-Os -fomit-frame-pointer -fno-strict-aliasing}}
385Some programs are very sensitive to the setting of the nursery (the first heap-generation). You
386should experiment with different nursery settings (either by compiling with the {{-nursery}}
387option or by using the {{-:s...}} runtime option).
388
389==== Which non-standard procedures are treated specially when the {{extended-bindings}} or {{usual-integrations}} declaration or compiler option is used?
390
391The following standard bindings are handled specially, depending on optimization options
392and compiler settings:
393
394{{*}}
395{{+}}
396{{-}}
397{{/}}
398{{<=}}
399{{<}}
400{{=}}
401{{>=}}
402{{>}}
403{{abs}}
404{{acos}}
405{{append}}
406{{apply}}
407{{asin}}
408{{assoc}}
409{{assv}}
410{{atan}}
411{{boolean?}}
412{{c...r}}
413{{call-with-current-continuation}}
414{{call-with-values}}
415{{ceiling}}
416{{char->integer}}
417{{char-alphabetic?}}
418{{char-downcase}}
419{{char-lower-case?}}
420{{char-numeric?}}
421{{char-upcae}}
422{{char-upper-case?}}
423{{char-whitespace?}}
424{{char<=?}}
425{{char<?}}
426{{char=?}}
427{{char>=?}}
428{{char>?}}
429{{char?}}
430{{complex?}}
431{{cons}}
432{{cos}}
433{{current-input-port}}
434{{current-output-port}}
435{{eof-object?}}
436{{eq?}}
437{{equal?}}
438{{eqv?}}
439{{even?}}
440{{exact->inexact}}
441{{exact?}}
442{{exp}}
443{{floor}}
444{{for-each}}
445{{gcd}}
446{{inexact->exact}}
447{{inexact?}}
448{{integer->char}}
449{{lcm}}
450{{length}}
451{{list-ref}}
452{{list-tail}}
453{{list?}}
454{{list}}
455{{log}}
456{{make-vector}}
457{{map}}
458{{member}}
459{{memq}}
460{{memv}}
461{{make-polar}}
462{{make-rectangular}}
463{{negative?}}
464{{not}}
465{{null?}}
466{{number->string}}
467{{number?}}
468{{odd?}}
469{{pair?}}
470{{positive?}}
471{{procedure?}}
472{{quotient}}
473{{rational?}}
474{{read-string}}
475{{real?}}
476{{remainder}}
477{{reverse}}
478{{round}}
479{{set-car!}}
480{{set-cdr!}}
481{{sin}}
482{{sqrt}}
483{{string->number}}
484{{string-append}}
485{{string-ci=?}}
486{{string-length}}
487{{string-ref}}
488{{string-set!}}
489{{string=?}}
490{{string?}}
491{{string}}
492{{substring}}
493{{symbol?}}
494{{tan}}
495{{truncate}}
496{{values}}
497{{vector-length}}
498{{vector-ref}}
499{{vector-set!}}
500{{vector?}}
501{{vector}}
502{{write-char}}
503{{zero?}}
504
505The following extended bindings are handled specially:
506
507{{add1}}
508{{any?}}
509{{arithmetic-shift}}
510{{atom?}}
511{{bignum?}}
512{{bit->boolean}}
513{{bitwise-and}}
514{{bitwise-ior}}
515{{bitwise-not}}
516{{bitwise-xor}}
517{{blob-size}}
518{{block-ref}}
519{{block-set!}}
520{{call/cc}}
521{{call-with-input-file}}
522{{call-with-output-file}}
523{{current-error-port}}
524{{current-thread}}
525{{error}}
526{{f32vector->blob/shared}}
527{{f32vector-length}}
528{{f32vector-ref}}
529{{f64vector->blob/shared}}
530{{f64vector-length}}
531{{f64vector-ref}}
532{{finite?}}
533{{fixnum?}}
534{{flonum?}}
535{{flush-output}}
536{{foldl}}
537{{foldr}}
538{{format}}
539{{fp*}}
540{{fp+}}
541{{fp-}}
542{{fp/}}
543{{fp<=}}
544{{fp<}}
545{{fp=}}
546{{fp>=}}
547{{fp>}}
548{{fpabs}}
549{{fpacos}}
550{{fpasin}}
551{{fpatan2}}
552{{fpatan}}
553{{fpceiling}}
554{{fpcos}}
555{{fpexpt}}
556{{fpexp}}
557{{fpfloor}}
558{{fpinteger?}}
559{{fplog}}
560{{fpmax}}
561{{fpmin}}
562{{fpneg}}
563{{fprintf}}
564{{fpround}}
565{{fpsin}}
566{{fpsqrt}}
567{{fptan}}
568{{fptruncate}}
569{{fx*?}}
570{{fx*}}
571{{fx+?}}
572{{fx+}}
573{{fx-?}}
574{{fx-}}
575{{fx/?}}
576{{fx/}}
577{{fx=}}
578{{fx>=}}
579{{fx>}}
580{{fxand}}
581{{fxeven?}}
582{{fxior}}
583{{fxmax}}
584{{fxmin}}
585{{fxmod}}
586{{fxneg}}
587{{fxnot}}
588{{fxodd?}}
589{{fxrem}}
590{{fxshl}}
591{{fxshr}}
592{{fxxor}}
593{{identity}}
594{{infinite?}}
595{{list->string}}
596{{list->vector}}
597{{locative->object}}
598{{locative-ref}}
599{{locative-set!}}
600{{locative?}}
601{{make-record-instance}}
602{{nan?}}
603{{number-of-slots}}
604{{o}}
605{{pointer+}}
606{{pointer->object}}
607{{pointer-f32-ref}}
608{{pointer-f32-set!}}
609{{pointer-f64-ref}}
610{{pointer-f64-set!}}
611{{pointer-s16-ref}}
612{{pointer-s16-set!}}
613{{pointer-s32-ref}}
614{{pointer-s32-set!}}
615{{pointer-s8-ref}}
616{{pointer-s8-set!}}
617{{pointer-u16-ref}}
618{{pointer-u16-set!}}
619{{pointer-u32-ref}}
620{{pointer-u32-set!}}
621{{pointer-u8-ref}}
622{{pointer-u8-set!}}
623{{pointer=?}}
624{{print*}}
625{{printf}}
626{{print}}
627{{s16vector->blob/shared}}
628{{s16vector-length}}
629{{s16vector-ref}}
630{{s16vector-set!}}
631{{s32vector->blob/shared}}
632{{s32vector-length}}
633{{s32vector-ref}}
634{{s32vector-set!}}
635{{s64vector->blob/shared}}
636{{s64vector-length}}
637{{s64vector-ref}}
638{{s64vector-set!}}
639{{s8vector->blob/shared}}
640{{s8vector-length}}
641{{s8vector-ref}}
642{{s8vector-set!}}
643{{signum}}
644{{sprintf}}
645{{string-append}}
646{{string->list}}
647{{sub1}}
648{{substring}}
649{{substring-ci=?}}
650{{substring-index-ci}}
651{{substring-index}}
652{{substring=?}}
653{{u16vector->blob/shared}}
654{{u16vector-length}}
655{{u16vector-ref}}
656{{u16vector-set!}}
657{{u32vector->blob/shared}}
658{{u32vector-length}}
659{{u32vector-ref}}
660{{u32vector-set!}}
661{{u64vector->blob/shared}}
662{{u64vector-length}}
663{{u64vector-ref}}
664{{u64vector-set!}}
665{{u8vector->blob/shared}}
666{{u8vector-length}}
667{{u8vector-ref}}
668{{u8vector-set!}}
669{{vector->list}}
670
671==== What's the difference betweem "block" and "local" mode?
672
673In {{block}} mode, the compiler assumes that definitions in the current file
674are not visible from outside of the current compilation unit, so unused
675definitions can be removed and calls can be inlined. In {{local}} mode,
676definitions are not hidden, but the compiler assumes that they are
677not modified from other compilation units (or code evaluated at runtime),
678and thus allows inlining of them.
679
680==== Can I load compiled code at runtime?
681
682Yes. You can load compiled at code at runtime with {{load}} just as
683well as you can load Scheme source code.  Compiled code will, of
684course, run faster.
685
686To do this, pass to {{load}} a path for a shared object.  Use a form
687such as {{(load "foo.so")}} and run {{csc -shared foo.scm}} to produce
688{{foo.so}} from {{foo.scm}} (at which point {{foo.scm}} will no longer
689be required).
690
691If you have compiled code that contains a {{module}} definition, then
692executing the code will "register" the module to allow importing the
693bindings provided by the module into a running Scheme process.
694The information required to use a module is in this case embedded in
695the compiled code. Compiling another program that uses this (compiled)
696module is more difficult: the used module will not necessarily be loaded
697into the compiler, so the registration will not be executed. In this
698case the information about what bindings the compiled module exports
699must be separated from the actual code that executes at runtime.
700To make this possible, compiling a module can be done in such a
701manner that an "import library" is created. This is a file that
702contains the binding information of the module and we can use it
703to compile a file that refers to that module. An example can perhaps
704make this clearer:
705
706  ;; my-module.scm
707 
708  (module my-module (...) ...)
709
710  ;; use-my-module.scm
711
712  (import my-module)
713  ...
714
715Compile the module and generate an import library for the "my-module" module:
716
717  % csc -s my-module.scm -emit-import-library my-module
718
719Compile the program that uses the module:
720
721  % csc use-my-module.scm
722
723==== Why is my program which uses regular expressions so slow?
724
725The regular expression engine has recently been replaced by [[/users/alex shinn|alex shinn]]'s excellent
726{{irregex}} library, which is fully implemented in Scheme. Precompiling regular
727expressions to internal forms is somewhat slower than with the old PCRE-based
728regex engine. It is advisable to use {{irregex}} to precompile regular expressions
729outside of time-critical loops and use them where performance matters.
730
731
732=== Garbage collection
733
734==== Why does a loop that doesn't {{cons}} still trigger garbage collections?
735
736Under CHICKEN's implementation policy, tail recursion is achieved simply by avoiding
737returns from function calls. Since the programs are CPS converted, a continuous
738sequence of nested procedure calls is performed. At some stage the stack-space has
739to run out and the current procedure and its parameters (including the current
740continuation) are stored somewhere in the runtime system. Now a minor garbage collection
741occurs and rescues all live
742data from the stack (the first heap generation) and moves it into the the second heap
743generation. Then the stack is cleared (using
744a {{longjmp}}) and execution can continue from the saved state.
745With this method arbitrary recursion (in tail- or non-tail position) can happen,
746provided the application doesn't run out of heap-space.
747(The difference between a tail- and a non-tail call is that the tail-call has no
748live data after it invokes its continuation - and so the amount of heap-space needed stays constant)
749
750==== Why do finalizers not seem to work in simple cases in the interpeter?
751
752Consider the following interaction in CSI:
753
754 #;1> (define x '(1 2 3))
755 #;2> (define (yammer x) (print x " is dead"))
756 #;3> (set-finalizer! x yammer)
757 (1 2 3)
758 #;4> (gc #t)
759 157812
760 #;5> (define x #f)
761 #;6> (gc #t)
762 157812
763 #;7>
764
765While you might expect objects to be reclaimed and "''(1 2 3) is dead''" printed, it won't happen:
766the literal list gets held in the interpreter history, because it is the
767result value of the set-finalizer! call.
768Running this in a normal program will work fine.
769
770When testing finalizers from the interpreter, you might want to define a trivial macro such as
771
772 (define-syntax v
773   (syntax-rules ()
774     ((_ x) (begin (print x) (void)))))
775
776and wrap calls to {{set-finalizer!}} in it.
777
778=== Interpreter
779
780==== Does CSI support history and autocompletion?
781
782CSI doesn't support it natively but it can be activated with one of the
783[[/egg/readline|readline]], [[/egg/linenoise|linenoise]] or
784[[/egg/parley|parley]] eggs. Out of these three, the parley egg is
785recommended. After installing parley, add the following to your
786{{~/.csirc}} or equivalent file:
787
788<enscript highlight=scheme>
789(import parley)
790(let ((old (current-input-port)))
791  (current-input-port (make-parley-port old)))
792</enscript>
793
794Users of *nix-like systems (including Cygwin), may also want to check out [[http://utopia.knoware.nl/~hlub/rlwrap/|rlwrap]].  This program lets you "wrap" another process (e.g. {{rlwrap csi}}) with the readline library, giving you history, autocompletion, and the ability to set the keystroke set. Vi fans can get vi keystrokes by adding "set editing-mode vi" to their {{.inputrc}} file.
795
796==== Does code loaded with {{load}} run compiled or interpreted?
797
798If you compile a file with a call to {{load}}, the code will be loaded at
799runtime and, if the file loaded is a Scheme source code file
800(instead of a shared object), it will be
801interpreted (even if the caller program is compiled).
802
803==== How do I use extended (non-standard) syntax in evaluated code at run-time?
804
805Normally, only standard Scheme syntax is available to the evaluator. To
806use the extensions provided in the CHICKEN compiler and interpreter,
807add:
808
809<enscript highlight=scheme>
810(require-library chicken-syntax)
811</enscript>
812
813=== Extensions
814
815==== Where is "chicken-setup" ?
816
817{{chicken-setup}} has been rewritten from scratch and its functionality is now
818contained in the three tools {{chicken-install}}, {{chicken-uninstall}} and {{chicken-status}}.
819See the [[Extensions]] chapter for more information.
820
821==== How can I install CHICKEN eggs to a non-default location?
822
823You can just set the {{CHICKEN_INSTALL_REPOSITORY}} and {{CHICKEN_REPOSITORY_PATH}}
824environment variables.
825They should contain the path where you want eggs to be installed:
826
827 $ export CHICKEN_INSTALL_REPOSITORY=~/eggs/lib/chicken/5
828 $ export CHICKEN_REPOSITORY_PATH=~/eggs/lib/chicken/5
829 $ chicken-install -init ~/eggs/lib/chicken/5
830 $ chicken-install -p ~/eggs/ extensionname
831
832In order to make programs (including csi) see these eggs, you should set {{CHICKEN_REPOSITORY_PATH}} when you run them. See the [[Extensions#Changing repository location|Extensions/Changing repository location]] section of the manual for more information on that.
833
834Alternatively, you can call the {{repository-path}} Scheme procedure before loading the eggs, as in:
835
836<enscript highlight=scheme>
837(repository-path "/home/azul/eggs")
838(import format-modular)
839</enscript>
840
841Note, however, that using {{repository-path}} as above hard-codes the location of your eggs in your source files.  While this might not be an issue in your case, it might be safe to keep this configuration outside of the source code (that is, specifying it as an environment variable) to make it easier to maintain.
842
843The repository needs to be initialized before use. See the documentation for the {{-init}} option
844to {{chicken-install}}, in [[Extensions]].
845
846==== Can I install chicken eggs as a non-root user?
847
848Yes, just install them in a directory you can write to by using {{CHICKEN_INSTALL_REPOSITORY}} (see above).
849
850==== Why does downloading an extension via {{chicken-install}} fail on Windows Vista?
851
852Possibly the Windows Firewall is active, which prevents {{chicken-install}} from opening a TCP
853connection to the egg repository. Try disabling the firewall temporarily.
854
855---
856Previous: [[Bugs and limitations]]
857
858Next: [[Acknowledgements]]
Note: See TracBrowser for help on using the repository browser.