📄 chicken-setup.html
字号:
<html><head><title>CHICKEN User's Manual - chicken-setup</title></head><body><p> </p><a name="chicken-setup"></a><h1>chicken-setup</h1><a name="extension-libraries"></a><h2>Extension libraries</h2><p>Extension libraries (<em>eggs</em>) are extensions to the core functionality provided by the basic CHICKEN system, to be built and installed separately. The mechanism for loading compiled extensions is based on dynamically loadable code and as such is only available on systems on which loading compiled code at runtime is supported. Currently these are most UNIX-compatible platforms that provide the <tt>libdl</tt> functionality like Linux, Solaris, BSD, Mac OS X and Windows using Cygwin.</p><p>Note: Extension may also be normal applications or shell scripts, but are usually libraries.</p><p><tt>chicken-setup</tt> will download the source code for extension automatically from the canonical server at <a href="http://www.call-with-current-continuation.org/eggs" class="external">http://www.call-with-current-continuation.org/eggs</a> if the requested egg does not exist in the current directory. Various command-line options exist for customizing the process and/or retrieving the egg from other locations or in other formats.</p><a name="installing-extensions"></a><h2>Installing extensions</h2><p>To install an extension library, run the <tt>chicken-setup</tt> program with the extension name as argument. The extension archive is downloaded, its contents extracted and the contained <em>setup</em> script is executed. This setup script is a normal Scheme source file, which will be interpreted by <tt>chicken-setup</tt>. The complete language supported by <tt>csi</tt> is available, and the library units <tt>srfi-1 regex utils posix tcp</tt> are loaded. Additional libraries can be loaded at run-time.</p><p>The setup script should perform all necessary steps to build the new library (or application). After a successful build, the extension can be installed by invoking one of the procedures <tt>install-extension</tt>, <tt>install-program</tt> or <tt>install-script</tt>. These procedures will copy a number of given files into the extension repository or in the path where the CHICKEN executables are located (in the case of executable programs or scripts). Additionally the list of installed files, and user-defined metadata is stored in the repository.</p><p>If no extension name is given on the command-line, and if none of the options <tt>-list</tt>, <tt>-version</tt>, <tt>-repository</tt> (without argument), <tt>-program-path</tt> (without argument), <tt>-fetch</tt>, <tt>-fetch-tree</tt> or <tt>-docindex</tt> is given, then all <tt>.setup</tt> scripts in the current directory are processed.</p><a name="installing-extensions-that-use-libraries"></a><h3>Installing extensions that use libraries</h3><p>Sometimes an extension requires a C library to compile. Compilation can fail when your system has this library in a nonstandard location. Luckily, normally Chicken searches in the default locations <tt>/usr</tt> and <tt>/usr/local</tt>, and in the prefix where Chicken itself was installed. Sometimes this is not enough, so you'll need to supply chicken-setup with some extra hints to the C compiler/linker. Here's an example:</p><pre> chicken-setup -c '-I/usr/pkg/include/mysql' -c '-L/usr/pkg/lib/mysql' -c '-L -R/usr/pkg/lib/mysql' mysql</pre><p>This installs the mysql egg with the extra compiler options -I and -L to set the include path and the library search path. The second -L switch passes the -R option directly to the linker, which causes the library path to get hardcoded into the resulting extension file (for systems that do not use ld.so.conf).</p><a name="creating-extensions"></a><h2>Creating extensions</h2><p>Extensions can be created by creating an (optionally gzipped) <tt>tar</tt> archive named <tt>EXTENSION.egg</tt> containing all needed files plus a <tt>.setup</tt> script in the root directory. After <tt>chicken-setup</tt> has extracted the files, the setup script will be invoked. There are no additional constraints on the structure of the archive, but the setup script has to be in the root path of the archive.</p><a name="procedures-and-macros-available-in-setup-scripts"></a><h2>Procedures and macros available in setup scripts</h2><a name="install-extension"></a><h3>install-extension</h3><pre>(install-extension ID FILELIST [INFOLIST])</pre><p>Installs the extension library with the name <tt>ID</tt>. All files given in the list of strings <tt>FILELIST</tt> will be copied to the extension repository. It should be noted here that the extension id has to be identical to the name of the file implementing the extension. The extension may load or include other files, or may load other extensions at runtime specified by the <tt>require-at-runtime</tt> property.</p><p><tt>FILELIST</tt> may be a filename, a list of filenames, or a list of pairs of the form <tt>(SOURCE DEST)</tt> (if you want to copy into a particular sub-directory - the destination directory will be created as needed). If <tt>DEST</tt> is a relative pathname, < it will be copied into the extension repository.</p><p>The optional argument <tt>INFOLIST</tt> should be an association list that maps symbols to values, this list will be stored as <tt>ID.setup-info</tt> at the same location as the extension code. Currently the following properties are used:</p><a name="syntax"></a><h4>syntax</h4><pre>[extension property] (syntax)</pre><p>Marks the extension as syntax-only. No code is compiled, the extension is intended as a file containing macros to be loaded at compile/macro-expansion time.</p><a name="require-at-runtime"></a><h4>require-at-runtime</h4><pre>[extension property] (require-at-runtime ID ...)</pre><p>Specifies extensions that should be loaded (via <tt>require</tt>) at runtime. This is mostly useful for syntax extensions that need additional support code at runtime.</p><a name="version"></a><h4>version</h4><pre>[extension property] (version STRING)</pre><p>Specifies version string.</p><a name="documentation"></a><h4>documentation</h4><pre>[extension property] (documentation FILENAME)</pre><p>The filename of a HTML document containing extension-specific documentation. This file should be given in the file-list passed to <tt>install-extension</tt> and a link to it will be automatically included in the index page (accessible via <tt>chicken-setup -docindex</tt>).</p><a name="examples"></a><h4>examples</h4><pre>[extension property] (examples FILENAME ...)</pre><p>Copies the given files into the examples directory, which is usually <tt>$prefix/share/chicken/examples</tt> or <tt>(make-pathname (chicken-home) "examples")</tt>).</p><p>Note that the files listed in this property should not be listed in the normal list of files to install passed to <tt>install-extension</tt>. This is the only exception - other files that are installed in the repository must be given in the file list.</p><a name="exports"></a><h4>exports</h4><pre>[extension property] (exports EXPORT ...)</pre><p>Add export-information to the generated extension-information. <tt>EXPORT</tt> may be a symbol naming an exported toplevel variable or a string designating a file with exported variables, as generated by the <tt>-emit-exports</tt> option or the <tt>emit-exports</tt> declaration specifier.</p><a name="static"></a><h4>static</h4><pre>[extension property] (static STRING)</pre><p>If the extension also provides a static library, then STRING should contain the name of that library. Used by <tt>csc</tt> when compiling with the <tt>-static-extensions</tt> option.</p><a name="static-options"></a><h4>static-options</h4><pre>[extension property] (static-options STRING)</pre><p>Additional options that should be passed to the linker when linking with the static version of an extension (see <tt>static</tt> above). Used by <tt>csc</tt> when compiling with the <tt>-static-extensions</tt> option.</p><p>All other properties are currently ignored. The <tt>FILELIST</tt> argument may also be a single string.</p><a name="install-program"></a><h3>install-program</h3><pre>[procedure] (install-program ID FILELIST [INFOLIST])</pre><p>Similar to <tt>install-extension</tt>, but installs an executable program in the executable path (usually <tt>/usr/local/bin</tt>).</p><a name="install-script"></a><h3>install-script</h3><pre>[procedure] (install-script ID FILELIST [INFOLIST])</pre><p>Similar to <tt>install-program</tt>, but additionally changes the file permissions of all files in <tt>FILELIST</tt> to executable (for installing shell-scripts).</p><a name="run"></a><h3>run</h3><pre>[syntax] (run FORM ...)</pre><p>Runs the shell command <tt>FORM</tt>, which is wrapped in an implicit <tt>quasiquote</tt>. <tt>(run (csc ...))</tt> is treated specially and passes <tt>-v</tt> (if <tt>-verbose</tt> has been given to <tt>chicken-setup</tt>) and <tt>-feature compiling-extension</tt> options to the compiler.</p><a name="compile"></a><h3>compile</h3><pre>[syntax] (compile FORM ...)</pre><p>Equivalent to <tt>(run (csc FORM ...))</tt>.</p><a name="make"></a><h3>make</h3><pre>[syntax] (make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)</pre><p>A <em>make</em> macro that executes the expressions <tt>COMMAND ...</tt>, when any of the dependents <tt>DEPENDENT ...</tt> have changed, to build <tt>TARGET</tt>. This is the same as the <tt>make</tt> extension, which is available separately. For more information, see <a href="http://www.call-with-current-continuation.org/eggs/make.html" class="external">make</a>.</p><a name="patch"></a><h3>patch</h3><pre>[procedure] (patch WHICH REGEX SUBST)</pre><p>Replaces all occurrences of the regular expression <tt>REGEX</tt> with the string <tt>SUBST</tt>, in the file given in <tt>WHICH</tt>. If <tt>WHICH</tt> is a string, the file will be patched and overwritten. If <tt>WHICH</tt> is a list of the form <tt>OLD NEW</tt>, then a different file named <tt>NEW</tt> will be generated.</p><a name="copy-file"></a><h3>copy-file</h3><pre>[procedure] (copy-file FROM TO)</pre><p>Copies the file or directory (recursively) given in the string <tt>FROM</tt> to the destination file or directory <tt>TO</tt>.</p><a name="move-file"></a><h3>move-file</h3><pre>[procedure] (move-file FROM TO)</pre><p>Moves the file or directory (recursively) given in the string <tt>FROM</tt> to the destination file or directory <tt>TO</tt>.</p><a name="remove-file"></a><h3>remove-file*</h3><pre>[procedure] (remove-file* PATH)</pre><p>Removes the file or directory given in the string <tt>PATH</tt>.</p><a name="find-library"></a><h3>find-library</h3><pre>[procedure] (find-library NAME PROC)</pre><p>Returns <tt>#t</tt> if the library named <tt>libNAME.[a|so]</tt> (unix) or <tt>NAME.lib</tt> (windows) could be found by compiling and linking a test program. <tt>PROC</tt> should be the name of a C function that must be provided by the library. If no such library was found or the function could not be resolved, <tt>#f</tt> is returned.</p><a name="find-header"></a><h3>find-header</h3><pre>[procedure] (find-header NAME)</pre><p>Returns <tt>#t</tt> if a C include-file with the given name is available, or <tt>#f</tt> otherwise.</p><a name="try-compile"></a><h3>try-compile</h3><pre>[procedure] (try-compile CODE #!key cc cflags ldflags compile-only c++)</pre><p>Returns <tt>#t</tt> if the C code in <tt>CODE</tt> compiles and links successfully, or <tt>#f</tt> otherwise. The keyword parameters <tt>cc</tt> (compiler name, defaults to the C compiler used to build this system), <tt>cflags</tt> and <tt>ldflags</tt> accept additional compilation and linking options. If <tt>compile-only</tt> is true, then no linking step takes place. If the keyword argument <tt>c++</tt> is given and true, then the code will be compiled in C++ mode.</p><a name="create-directory"></a><h3>create-directory</h3><pre>[procedure] (create-directory PATH)</pre><p>Creates the directory given in the string <tt>PATH</tt>, with all parent directories as needed.</p><a name="chicken-prefix"></a><h3>chicken-prefix</h3><pre>[parameter] chicken-prefix</pre><p>The installation prefix specified when CHICKEN was built.</p><a name="installation-prefix"></a><h3>installation-prefix</h3><pre>[parameter] installation-prefix</pre><p>An alternative installation prefix that will be prepended to extension installation paths if specified. It is set by the <tt>-install-prefix</tt> option or environment variable <tt>CHICKEN_INSTALL_PREFIX</tt>.</p><a name="program-path"></a><h3>program-path</h3><pre>[parameter] (program-path [PATH])</pre><p>Holds the path where executables are installed and defaults to either <tt>$CHICKEN_PREFIX/bin</tt>, if the environment variable <tt>CHICKEN_PREFIX</tt> is set or the path where the CHICKEN binaries (<tt>chicken</tt>, <tt>csi</tt>, etc.) are installed.</p><a name="setup-root-directory"></a><h3>setup-root-directory</h3><pre>[parameter] (setup-root-directory [PATH])</pre><p>Contains the path of the directory where <tt>chicken-setup</tt> was invoked.</p><a name="setup-build-directory"></a><h3>setup-build-directory</h3><pre>[parameter] (setup-build-directory [PATH])</pre><p>Contains the path of the directory where the extension is built. This is not necessarily identical to <tt>setup-root-directory</tt>.</p><a name="setup-verbose-flag"></a><h3>setup-verbose-flag</h3><pre>[parameter] (setup-verbose-flag [BOOL])</pre><p>Reflects the setting of the <tt>-verbose</tt> option, i.e. is <tt>#t</tt>, if <tt>-verbose</tt> was given.</p><a name="setup-install-flag"></a><h3>setup-install-flag</h3><pre>[parameter] (setup-install-flag [BOOL])</pre><p>Reflects the setting of the <tt>--no-install</tt> option, i.e. is <tt>#f</tt>, if <tt>-no-install</tt> was given.</p><a name="required-chicken-version"></a><h3>required-chicken-version</h3><pre>[procedure] (required-chicken-version VERSION)</pre><p>Signals an error if the version of CHICKEN that this script runs under is lexicographically less than <tt>VERSION</tt> (the argument will be converted to a string, first).</p><a name="required-extension-version"></a><h3>required-extension-version</h3><pre>[procedure] (required-extension-version EXTENSION1 VERSION1 ...)</pre><p>Checks whether the extensions <tt>EXTENSION1 ...</tt> are installed and at least of version <tt>VERSION1 ...</tt>. The test is made by lexicographically comparing the string-representations of the given version with the version of the installed extension. If one of the listed extensions is not installed, has no associated version information or is of a version older than the one specified.</p><a name="cross-chicken"></a><h3>cross-chicken</h3><pre>[procedure] (cross-chicken)</pre><p>Returns <tt>#t</tt> if this system is configured for cross-compilation or <tt>#f</tt> otherwise.</p><a name="host-extension"></a><h3>host-extension</h3><pre>[parameter] host-extension</pre><p>For a cross-compiling CHICKEN, when compiling an extension, then it should be built for the host environment (as opposed to the target environment). This parameter is controlled by the <tt>-host-extension</tt> command-line option. A setup script should perform the proper steps of compiling any code by passing <tt>-host</tt> when invoking <tt>csc</tt> or using the <tt>compile</tt> macro.</p><a name="examples-for-extensions"></a><h2>Examples for extensions</h2><p>The simplest case is a single file that does not export any syntax. For example</p><PRE><I><FONT COLOR="#B22222">;;;; hello.scm</FONT></I>(<B><FONT COLOR="#A020F0">define</FONT></B> (<B><FONT COLOR="#0000FF">hello</FONT></B> name) (print <B><FONT COLOR="#BC8F8F">"Hello, "</FONT></B> name <B><FONT COLOR="#BC8F8F">" !"</FONT></B>) )</PRE><p>We need a <tt>.setup</tt> script to build and install our nifty extension:</p><PRE><I><FONT COLOR="#B22222">;;;; hello.setup</FONT></I><I><FONT COLOR="#B22222">;; compile the code into a dynamically loadable shared object</FONT></I><I><FONT COLOR="#B22222">;; (will generate hello.so)</FONT></I>(compile -s hello.scm)<I><FONT COLOR="#B22222">;; Install as extension library</FONT></I>(install-extension 'hello <B><FONT COLOR="#BC8F8F">"hello.so"</FONT></B>)</PRE><p>After entering </p><pre>$ chicken-setup hello</pre><p>at the shell prompt (and in the same directory where the two files exist), the file <tt>hello.scm</tt> will be compiled into a dynamically loadable library. If the compilation succeeds, <tt>hello.so</tt> will be stored in the repository, together with a file named <tt>hello.setup-info</tt> containing an a-list with metadata. If no extension name is given to <tt>chicken-setup</tt>, it will simply execute the first file with the <tt>.setup</tt> extension it can find.</p><p>Use it like any other CHICKEN extension:</p><pre>$ csi -q#;1> (require-extension hello); loading /usr/local/lib/chicken/1/hello.so ...#;2> (hello "me")Hello, me!#;3></pre><p>Here we create a simple application:</p><PRE><I><FONT COLOR="#B22222">;;;; hello2.scm</FONT></I>(print <B><FONT COLOR="#BC8F8F">"Hello, "</FONT></B>)(for-each (<B><FONT COLOR="#A020F0">lambda</FONT></B> (x) (printf <B><FONT COLOR="#BC8F8F">"~A "</FONT></B> x)) (command-line-arguments))(print <B><FONT COLOR="#BC8F8F">"!"</FONT></B>)</PRE><p>We also need a setup script:</p><PRE><I><FONT COLOR="#B22222">;;;; hello2.setup</FONT></I>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -