870 lines
41 KiB
HTML
870 lines
41 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
<title>System building (ECL Manual)</title>
|
||
|
||
<meta name="description" content="System building (ECL Manual)">
|
||
<meta name="keywords" content="System building (ECL Manual)">
|
||
<meta name="resource-type" content="document">
|
||
<meta name="distribution" content="global">
|
||
<meta name="Generator" content="makeinfo">
|
||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
||
<link href="index.html" rel="start" title="Top">
|
||
<link href="Indexes.html" rel="index" title="Indexes">
|
||
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
<link href="Extensions.html" rel="up" title="Extensions">
|
||
<link href="Operating-System-Interface.html#Operating-System-Interface" rel="next" title="Operating System Interface">
|
||
<style type="text/css">
|
||
<!--
|
||
/* colors */
|
||
|
||
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
||
div.example {margin-left: 3.2em}
|
||
span.r {font-family: initial; font-weight: normal; font-style: normal}
|
||
span:hover a.copiable-link {visibility: visible}
|
||
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
||
ul.mark-bullet {list-style-type: disc}
|
||
@media (prefers-color-scheme: dark) {
|
||
/* dark theme */
|
||
html { color: seashell;
|
||
background: #1A1A1A; }
|
||
body { background: #1A1A1A; }
|
||
th { border-bottom: 2px solid lightgray; }
|
||
h1, h2, h3, h4, h5 { background-image: linear-gradient(to left, #202020, #3A3A3A); }
|
||
code, var, code a { color: darkorange;
|
||
background: #2A2A2A; }
|
||
a { color: seashell; }
|
||
pre { background: #2A2A2A;
|
||
color: seashell;
|
||
/* mark longer code block with stripe on the left */
|
||
border-left: 5px solid darkorange;
|
||
padding-left: 10px; }
|
||
pre.screen { background: #2A2A2A;
|
||
border: 1px solid lightgray; }
|
||
pre.programlisting { background: #2A2A2A;
|
||
border-left: 1px solid lightgray;
|
||
border-top: 1px solid lightgray; }
|
||
/* we need a light background in order for the images to be readable */
|
||
img { background: white }
|
||
}
|
||
@media (prefers-color-scheme: light) {
|
||
/* light theme */
|
||
html { background: white }
|
||
body { background: white }
|
||
th { border-bottom: 2px solid gray; }
|
||
h1, h2, h3, h4, h5 { background: lightgray; }
|
||
code, var, code a { color: darkred;
|
||
background: whitesmoke; }
|
||
a { color: #000; }
|
||
pre { background: whitesmoke;
|
||
color: black;
|
||
/* mark longer code block with stripe on the left */
|
||
border-left: 5px solid darkred;
|
||
padding-left: 10px; }
|
||
pre.screen { background: #EEE;
|
||
border: 1px solid black; }
|
||
pre.programlisting { background: #EEEEEE;
|
||
border-left: 1px solid black;
|
||
border-top: 1px solid black; }
|
||
}
|
||
|
||
body {
|
||
margin: 1em 125px 0 10%;
|
||
line-height: 1.5em;
|
||
padding: 0 2em 1em 2em;
|
||
font: 13px Verdana,Arial, sans-serif
|
||
}
|
||
ul, dd, dl, dt { margin-top: 0; margin-bottom: 0; }
|
||
p, code, td, dl, dt {
|
||
line-height: 1.5em;
|
||
}
|
||
table {
|
||
font: inherit;
|
||
border-collapse: collapse;
|
||
}
|
||
th, td {
|
||
vertical-align: top;
|
||
}
|
||
h1, h2, h3 { padding-left: 15px; }
|
||
h4, h5 { padding-left: 5px; }
|
||
code, pre {
|
||
font-size: 1em;
|
||
font-family: monospace;
|
||
}
|
||
var {
|
||
font-size: 1em;
|
||
}
|
||
/* links inside code appear the same as the code itself */
|
||
code a {
|
||
font-weight: normal;
|
||
text-decoration: none;
|
||
}
|
||
/* but get an underline when hovering */
|
||
code a:hover {
|
||
text-decoration: underline;
|
||
}
|
||
/* ordinary links appear in bold */
|
||
a { font-weight: bold; }
|
||
pre.verbatim {
|
||
margin: 0 0 0 0;
|
||
}
|
||
pre {
|
||
overflow: auto;
|
||
}
|
||
pre.screen {
|
||
font-weight: bold;
|
||
padding: 0.5em;
|
||
}
|
||
pre.programlisting {
|
||
padding: 0.5em;
|
||
}
|
||
div p { padding: 0 2em }
|
||
li p { padding: 0; margin: 0 }
|
||
hr { display: none; }
|
||
div.funcsynopsis p {
|
||
text-indent: -2em;
|
||
}
|
||
div.variablelist {
|
||
padding: 0 2em;
|
||
}
|
||
.type, .funcsynopsis, .symbol {
|
||
font-family: monospace;
|
||
}
|
||
.type, .symbol, .replaceable {
|
||
white-space: nowrap;
|
||
}
|
||
|
||
-->
|
||
</style>
|
||
|
||
|
||
</head>
|
||
|
||
<body lang="en">
|
||
<div class="section-level-extent" id="System-building">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="Operating-System-Interface.html#Operating-System-Interface" accesskey="n" rel="next">Operating System Interface</a>, Up: <a href="Extensions.html" accesskey="u" rel="up">Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h3 class="section" id="System-building-1">3.1 System building</h3>
|
||
|
||
|
||
<a class="index-entry-id" id="index-System-building"></a>
|
||
<a class="index-entry-id" id="index-Creating-executables-and-libraries"></a>
|
||
|
||
<ul class="mini-toc">
|
||
<li><a href="System-building.html#Compiling-with-ECL" accesskey="1">Compiling with ECL</a></li>
|
||
<li><a href="System-building.html#Compiling-with-ASDF" accesskey="2">Compiling with ASDF</a></li>
|
||
<li><a href="System-building.html#C-compiler-configuration" accesskey="3">C compiler configuration</a></li>
|
||
</ul>
|
||
<hr>
|
||
<div class="subsection-level-extent" id="Compiling-with-ECL">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Compiling-with-ASDF" accesskey="n" rel="next">Compiling with ASDF</a>, Up: <a href="System-building.html#System-building" accesskey="u" rel="up">System building</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsection" id="Compiling-with-ECL-1">3.1.1 Compiling with ECL</h4>
|
||
|
||
<p>In this section we will introduce topics on compiling Lisp
|
||
programs. ECL is especially powerful on combining lisp programs with C
|
||
programs. You can embed ECL as a lisp engine in C programs, or call C
|
||
functions via <a class="ref" href="Foreign-Function-Interface.html#Foreign-Function-Interface">Foreign Function Interface</a>. We explain file types
|
||
generated by some compilation approaches. For the examples,
|
||
a GNU/Linux system and gcc as a development environment are assumed.
|
||
</p>
|
||
<p>You can generate the following files with ECL:
|
||
</p>
|
||
<ol class="enumerate">
|
||
<li> Portable FASL file (.fasc)
|
||
</li><li> Native FASL file (.fas, .fasb)
|
||
</li><li> Object file (.o)
|
||
</li><li> Static library
|
||
</li><li> Shared library
|
||
</li><li> Executable file
|
||
</li></ol>
|
||
|
||
<p>Relations among them are depicted below:
|
||
</p>
|
||
<div class="float" id="fig_003afile_005ftypes">
|
||
|
||
<img class="image" src="figures/file-types.png" alt="figures/file-types">
|
||
<div class="caption"><p><strong class="strong">Figure 3.1: </strong>Build file types</p></div></div>
|
||
|
||
<ul class="mini-toc">
|
||
<li><a href="System-building.html#Portable-FASL-_0028fasc_0029" accesskey="1">Portable FASL</a></li>
|
||
<li><a href="System-building.html#Native-FASL" accesskey="2">Native FASL</a></li>
|
||
<li><a href="System-building.html#Object-file" accesskey="3">Object file</a></li>
|
||
<li><a href="System-building.html#Static-library" accesskey="4">Static library</a></li>
|
||
<li><a href="System-building.html#Shared-library" accesskey="5">Shared library</a></li>
|
||
<li><a href="System-building.html#Executable" accesskey="6">Executable</a></li>
|
||
<li><a href="System-building.html#Summary" accesskey="7">Summary</a></li>
|
||
</ul>
|
||
<hr>
|
||
<div class="subsubsection-level-extent" id="Portable-FASL-_0028fasc_0029">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Native-FASL" accesskey="n" rel="next">Native FASL</a>, Up: <a href="System-building.html#Compiling-with-ECL" accesskey="u" rel="up">Compiling with ECL</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Portable-FASL">3.1.1.1 Portable FASL</h4>
|
||
<a class="index-entry-id" id="index-Portable-FASL"></a>
|
||
|
||
<p>ECL provides two compilers (bytecodes compiler, and C/C++
|
||
compiler). Portable FASL files are built from source lisp files by the
|
||
bytecodes compiler. Generally FASC files are portable across
|
||
architectures and operating systems providing a convenient way of shipping
|
||
portable modules. Portable FASL files may be concatenated, what leads to
|
||
bundles. FASC files are faster to compile, but generally slower to run.
|
||
</p>
|
||
<a class="index-entry-id" id="index-Building-Portable-FASL-file"></a>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">;; install bytecodes compiler
|
||
(ext:install-bytecodes-compiler)
|
||
|
||
;; compile hello.lisp file to hello.fasc
|
||
(compile-file "hello1.lisp")
|
||
(compile-file "hello2.lisp")
|
||
|
||
;; reinitialize C/C++ compiler back
|
||
(ext:install-c-compiler)
|
||
|
||
;; FASC file may be loaded dynamically from lisp program
|
||
(load "hello1.fasc")
|
||
|
||
;; ... concatenated into a bundle with other FASC
|
||
(with-open-file (output "hello.fasc"
|
||
:direction :output
|
||
:if-exists :supersede)
|
||
(ext:run-program
|
||
"cat" '("hello1.fasc" "hello2.fasc") :output output))
|
||
|
||
;; ... and loaded dynamically from lisp program
|
||
(load "hello.fasc")
|
||
</pre></div>
|
||
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Native-FASL">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Object-file" accesskey="n" rel="next">Object file</a>, Previous: <a href="System-building.html#Portable-FASL-_0028fasc_0029" accesskey="p" rel="prev">Portable FASL</a>, Up: <a href="System-building.html#Compiling-with-ECL" accesskey="u" rel="up">Compiling with ECL</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Native-FASL-1">3.1.1.2 Native FASL</h4>
|
||
|
||
<a class="index-entry-id" id="index-Native-FASL"></a>
|
||
<a class="index-entry-id" id="index-DLOPEN"></a>
|
||
<a class="index-entry-id" id="index-_002d_002denable_002dshared-_005bYES_007cno_005d"></a>
|
||
|
||
|
||
<p>If you want to make a library which is loaded dynamically from a lisp
|
||
program, you should choose the fasl file format. Under the hood native fasls
|
||
are just shared library files.
|
||
</p>
|
||
<p>This means you can load fasl files with <code class="code">dlopen</code> and initialize it
|
||
by calling a init function from C programs, but this is not an intended
|
||
usage. The recommended usage is to load fasl files by calling the load lisp
|
||
function. To work with <em class="emph">Native FASL files</em> ECL has to be compiled
|
||
with <code class="code">--enable-shared</code> configure option (enabled by default).
|
||
</p>
|
||
<p>Creating a fasl file from one lisp file is very easy.
|
||
</p>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">(compile-file "hello.lisp")
|
||
</pre></div>
|
||
|
||
<p>To create a fasl file from more lisp files, firstly you have to compile
|
||
each lisp file into an object file, and then combine them with
|
||
<code class="code">c:build-fasl</code>.
|
||
</p>
|
||
<a class="index-entry-id" id="index-Building-native-FASL"></a>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">;; generates hello.o
|
||
(compile-file "hello.lisp" :system-p t)
|
||
;; generates goodbye.o
|
||
(compile-file "goodbye.lisp" :system-p t)
|
||
|
||
;; generates hello-goodbye.fas
|
||
(c:build-fasl "hello-goodbye"
|
||
:lisp-files '("hello.o" "goodbye.o"))
|
||
|
||
;; fasls may be built from mix of objects and libraries (both shared and
|
||
;; static)
|
||
(c:build-fasl "mixed-bundle"
|
||
:lisp-files '("hello1.o" "hello2.a" "hello3.so"))
|
||
</pre></div>
|
||
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Object-file">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Static-library" accesskey="n" rel="next">Static library</a>, Previous: <a href="System-building.html#Native-FASL" accesskey="p" rel="prev">Native FASL</a>, Up: <a href="System-building.html#Compiling-with-ECL" accesskey="u" rel="up">Compiling with ECL</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Object-file-1">3.1.1.3 Object file</h4>
|
||
|
||
<p>Object files work as an intermediate file format. If you want to compile
|
||
more than two lisp files, you might better to compile with a
|
||
<code class="code">:system-p t</code> option, which generates object files (instead of a
|
||
fasl).
|
||
</p>
|
||
<p>On linux systems, ECL invokes <code class="code">gcc -c</code> to generate object files.
|
||
</p>
|
||
<p>An object file consists of some functions in C:
|
||
</p>
|
||
<ul class="itemize mark-bullet">
|
||
<li>Functions corresponding to Lisp functions
|
||
</li><li>The initialization function which registers defined functions on the lisp environment
|
||
</li></ul>
|
||
|
||
<p>Consider the example below.
|
||
</p>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">(defun say-hello ()
|
||
(print "Hello, world"))
|
||
</pre></div>
|
||
|
||
<a class="index-entry-id" id="index-Object-file-internal-layout"></a>
|
||
<p>During compilation, this simple lisp program is translated into the C
|
||
program, and then compiled into the object file. The C program contains
|
||
two functions:
|
||
</p>
|
||
<ul class="itemize mark-bullet">
|
||
<li><code class="code">static cl_object L1say_hello</code>:
|
||
’say-hello’ function
|
||
|
||
</li><li><code class="code">ECL_DLLEXPORT void _eclwm2nNauJEfEnD_CLSxi0z(cl_object flag)</code>:
|
||
initialization function
|
||
|
||
</li></ul>
|
||
|
||
<p>In order to use these object files from your C program, you have to call
|
||
initialization functions before using lisp functions (such as
|
||
<code class="code">say-hello</code>). However the name of an init function is seemed to be
|
||
randomized and not user-friendly. This is because object files are not
|
||
intended to be used directly.
|
||
</p>
|
||
<p>ECL provides other user-friendly ways to generate compiled lisp programs
|
||
(as static/shared libraries or executables), and in each approach, object
|
||
files act as intermediate files.
|
||
</p>
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Static-library">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Shared-library" accesskey="n" rel="next">Shared library</a>, Previous: <a href="System-building.html#Object-file" accesskey="p" rel="prev">Object file</a>, Up: <a href="System-building.html#Compiling-with-ECL" accesskey="u" rel="up">Compiling with ECL</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Static-library-1">3.1.1.4 Static library</h4>
|
||
|
||
<p>ECL can compile lisp programs to static libraries, which can be linked
|
||
with C programs. A static library is created by
|
||
<code class="code">c:build-static-library</code> with some compiled object files.
|
||
</p>
|
||
<a class="index-entry-id" id="index-Building-static-library"></a>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">;; generates hello.o
|
||
(compile-file "hello.lsp" :system-p t)
|
||
;; generates goodbye.o
|
||
(compile-file "goodbye.lsp" :system-p t)
|
||
|
||
;; generates libhello-goodbye.a
|
||
(c:build-static-library "hello-goodbye"
|
||
:lisp-files '("hello.o" "goodbye.o")
|
||
:init-name "init_hello_goodbye")
|
||
</pre></div>
|
||
|
||
<p>When you use a static/shared library, you have to call its init function. The
|
||
name of this function is specified by the <code class="code">:init-name</code> option. In this
|
||
example, it is then <code class="code">init_hello_goodbye</code>. The usage of this function is
|
||
shown below:
|
||
</p>
|
||
<a class="anchor" id="ecl_005finit_005fmodule"></a><a class="index-entry-id" id="index-ecl_005finit_005fmodule"></a>
|
||
<a class="index-entry-id" id="index-Initializing-static_002fshared-library-in-C_002fC_002b_002b"></a>
|
||
<div class="example">
|
||
<pre class="verbatim">#include <ecl/ecl.h>
|
||
extern void init_hello_goodbye(cl_object cblock);
|
||
|
||
int
|
||
main(int argc, char **argv)
|
||
{
|
||
/* setup the lisp runtime */
|
||
cl_boot(argc, argv);
|
||
|
||
/* call the init function via ecl_init_module */
|
||
ecl_init_module(NULL, init_hello_goodbye);
|
||
|
||
/* ... */
|
||
|
||
/* shutdown the lisp runtime */
|
||
cl_shutdown();
|
||
|
||
return 0;
|
||
}
|
||
</pre></div>
|
||
|
||
<p>Because the program itself does not know the type of the init function,
|
||
a prototype declaration is inserted. After booting up the lisp
|
||
environment, it invokes <code class="code">init_hello_goodbye</code> via
|
||
<code class="code"><a class="ref" href="System-building.html#ecl_005finit_005fmodule">ecl_init_module</a></code>. <code class="code">init_hello_goodbye</code> takes an argument,
|
||
and <code class="code"><a class="ref" href="System-building.html#ecl_005finit_005fmodule">ecl_init_module</a></code> supplies an appropriate one. Now that the
|
||
initialization is finished, we can use functions and other stuff defined
|
||
in the library.
|
||
</p>
|
||
<p><strong class="strong">DEPRECATED</strong> <code class="code">read_VV</code> - equivalent to <code class="code"><a class="ref" href="System-building.html#ecl_005finit_005fmodule">ecl_init_module</a></code>
|
||
</p>
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Shared-library">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Executable" accesskey="n" rel="next">Executable</a>, Previous: <a href="System-building.html#Static-library" accesskey="p" rel="prev">Static library</a>, Up: <a href="System-building.html#Compiling-with-ECL" accesskey="u" rel="up">Compiling with ECL</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Shared-library-1">3.1.1.5 Shared library</h4>
|
||
|
||
<p>Almost the same as with a static library. The user has to use
|
||
<code class="code">c:build-shared-library</code>:
|
||
</p>
|
||
<a class="index-entry-id" id="index-Building-shared-library"></a>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">;; generates hello.o
|
||
(compile-file "hello.lsp" :system-p t)
|
||
;; generates goodbye.o
|
||
(compile-file "goodbye.lsp" :system-p t)
|
||
|
||
;; generates libhello-goodbye.so
|
||
(c:build-shared-library "hello-goodbye"
|
||
:lisp-files '("hello.o" "goodbye.o")
|
||
:init-name "init_hello_goodbye")
|
||
</pre></div>
|
||
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Executable">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Summary" accesskey="n" rel="next">Summary</a>, Previous: <a href="System-building.html#Shared-library" accesskey="p" rel="prev">Shared library</a>, Up: <a href="System-building.html#Compiling-with-ECL" accesskey="u" rel="up">Compiling with ECL</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Executable-1">3.1.1.6 Executable</h4>
|
||
|
||
<p>ECL supports the generation of executable files. To create a standalone
|
||
executable from a lisp program, compile all lisp files to object
|
||
files. After that, calling <code class="code">c:build-program</code> creates the
|
||
executable:
|
||
</p>
|
||
<a class="index-entry-id" id="index-Building-executable"></a>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">;; generates hello.o
|
||
(compile-file "hello.lsp" :system-p t)
|
||
;; generates goodbye.o
|
||
(compile-file "goodbye.lsp" :system-p t)
|
||
|
||
;; generates hello-goodbye
|
||
(c:build-program "hello-goodbye"
|
||
:lisp-files '("hello.o" "goodbye.o"))
|
||
</pre></div>
|
||
|
||
<p>Like with native FASL, the program may be built also from libraries.
|
||
</p>
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Summary">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Previous: <a href="System-building.html#Executable" accesskey="p" rel="prev">Executable</a>, Up: <a href="System-building.html#Compiling-with-ECL" accesskey="u" rel="up">Compiling with ECL</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Summary-1">3.1.1.7 Summary</h4>
|
||
|
||
<p>In this section, some file types that can be compiled with ECL were
|
||
introduced. Each file type has an adequate purpose:
|
||
</p>
|
||
<ul class="itemize mark-bullet">
|
||
<li>Object file: intermediate file format for others
|
||
</li><li>Fasl files: loaded dynamically via the <code class="code">load</code> lisp function
|
||
</li><li>Static library: linked with and used from C programs
|
||
</li><li>Shared library: loaded dynamically and used from C programs
|
||
</li><li>Executable: standalone executable
|
||
</li></ul>
|
||
|
||
<p>ECL provides a high-level interface <code class="code">c:build-*</code> for each native
|
||
format. In case of <em class="emph">Portable FASL</em> the bytecodes compiler is needed.
|
||
</p>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="subsection-level-extent" id="Compiling-with-ASDF">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#C-compiler-configuration" accesskey="n" rel="next">C compiler configuration</a>, Previous: <a href="System-building.html#Compiling-with-ECL" accesskey="p" rel="prev">Compiling with ECL</a>, Up: <a href="System-building.html#System-building" accesskey="u" rel="up">System building</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsection" id="Compiling-with-ASDF-1">3.1.2 Compiling with ASDF</h4>
|
||
|
||
<p>For larger systems involving more complex file dependencies, or for systems
|
||
that are portable across different Common Lisp implementations, it may be
|
||
better to define systems using <a class="uref" href="https://common-lisp.net/project/asdf/">asdf</a>.
|
||
</p>
|
||
<p>ECL provides a useful extension for asdf called <code class="code">asdf:make-build</code>, which
|
||
offers an abstraction for building libraries directly from system definitions.
|
||
Note that this extension is only available in the ASDF that is shipped with
|
||
ECL; it may not be available from an ASDF installed from the system or from
|
||
Quicklisp.
|
||
</p>
|
||
<p>To download dependencies you may use
|
||
<a class="uref" href="https://www.quicklisp.org">Quicklisp</a> to load your system (with
|
||
dependencies defined). Make sure you can successfully load and run your
|
||
library in the ECL REPL (or <code class="code">*slime-repl*</code>). Don’t worry about
|
||
other libraries loaded in your image – ECL will only build and pack
|
||
libraries your project depends on (that is, all dependencies you put in
|
||
your <code class="code">.asd</code> file, and their dependencies - nothing more, despite
|
||
the fact that other libraries may be loaded).
|
||
</p>
|
||
|
||
<ul class="mini-toc">
|
||
<li><a href="System-building.html#Example-code-to-build" accesskey="1">Example code to build</a></li>
|
||
<li><a href="System-building.html#Build-it-as-an-single-executable" accesskey="2">Build it as an single executable</a></li>
|
||
<li><a href="System-building.html#Build-it-as-shared-library-and-use-in-C" accesskey="3">Build it as shared library and use in C</a></li>
|
||
<li><a href="System-building.html#Build-it-as-static-library-and-use-in-C" accesskey="4">Build it as static library and use in C</a></li>
|
||
</ul>
|
||
<hr>
|
||
<div class="subsubsection-level-extent" id="Example-code-to-build">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Build-it-as-an-single-executable" accesskey="n" rel="next">Build it as an single executable</a>, Up: <a href="System-building.html#Compiling-with-ASDF" accesskey="u" rel="up">Compiling with ASDF</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Example-code-to-build-1">3.1.2.1 Example code to build</h4>
|
||
|
||
<p>An example project is included in the ECL source distribution in the
|
||
<code class="code">examples/asdf_with_dependence/</code> directory.
|
||
</p>
|
||
<p>This project depends on the <code class="code">alexandria</code> library and consists of a system
|
||
definition (<code class="code">example-with-dep.asd</code>), package definition
|
||
(<code class="code">package.lisp</code>), and the actual library code (<code class="code">example.lisp</code>).
|
||
</p>
|
||
<p>Before following the steps below, you must
|
||
<a class="uref" href="https://asdf.common-lisp.dev/asdf/Configuring-ASDF-to-find-your-systems.html">configure ASDF to find your systems</a>.
|
||
You can either copy or symlink the example directory in one of the standard
|
||
ASDF locations, or push the path of the example directory to your
|
||
<code class="code">asdf:*central-registry*</code>, for example:
|
||
</p>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">(push "./" asdf:*central-registry*)
|
||
</pre></div>
|
||
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Build-it-as-an-single-executable">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Build-it-as-shared-library-and-use-in-C" accesskey="n" rel="next">Build it as shared library and use in C</a>, Previous: <a href="System-building.html#Example-code-to-build" accesskey="p" rel="prev">Example code to build</a>, Up: <a href="System-building.html#Compiling-with-ASDF" accesskey="u" rel="up">Compiling with ASDF</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Build-it-as-an-single-executable-1">3.1.2.2 Build it as an single executable</h4>
|
||
|
||
<p>Use this in the REPL to make an executable:
|
||
</p>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">(asdf:make-build :example-with-dep
|
||
:type :program
|
||
:move-here #P"./"
|
||
:epilogue-code '(progn (example:test-function 5)
|
||
(si:exit)))
|
||
</pre></div>
|
||
|
||
<p>Here the <code class="code">:epilogue-code</code> is executed after loading our library;
|
||
we can use arbitrary Lisp forms here. You can also put this code in
|
||
your Lisp files and directly build them without this
|
||
<code class="code">:epilogue-code</code> option to achieve the same result. Running the
|
||
program in a console will display the following and exit:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">Factorial of 5 is: 120
|
||
</pre></div>
|
||
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Build-it-as-shared-library-and-use-in-C">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="System-building.html#Build-it-as-static-library-and-use-in-C" accesskey="n" rel="next">Build it as static library and use in C</a>, Previous: <a href="System-building.html#Build-it-as-an-single-executable" accesskey="p" rel="prev">Build it as an single executable</a>, Up: <a href="System-building.html#Compiling-with-ASDF" accesskey="u" rel="up">Compiling with ASDF</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Build-it-as-shared-library-and-use-in-C-1">3.1.2.3 Build it as shared library and use in C</h4>
|
||
|
||
<p>Use this in the REPL to make a shared library:
|
||
</p>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">(asdf:make-build :example-with-dep
|
||
:type :shared-library
|
||
:move-here #P"./"
|
||
:monolithic t
|
||
:init-name "init_dll_example")
|
||
</pre></div>
|
||
|
||
<p>Here <code class="code">:monolithic t</code> means that ECL will compile the library and
|
||
all its dependencies into a single library named
|
||
<code class="code">example-with-dep--all-systems.so</code>. The <code class="code">:move-here</code>
|
||
parameter is self-explanatory. <code class="code">:init-name</code> sets the name of the
|
||
initialization function. Each library linked from C/C++ code must be
|
||
initialized, and this is a mechanism to specify the initialization
|
||
function’s name.
|
||
</p>
|
||
<p>To use it, we write a simple C program:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="verbatim">/* test.c */
|
||
#include <ecl/ecl.h>
|
||
extern void init_dll_example(cl_object);
|
||
|
||
int main (int argc, char **argv) {
|
||
|
||
cl_boot(argc, argv);
|
||
ecl_init_module(NULL, init_dll_example);
|
||
|
||
/* do things with the Lisp library */
|
||
cl_eval(c_string_to_object("(example:test-function 5)"));
|
||
|
||
cl_shutdown();
|
||
return 0;
|
||
}
|
||
</pre></div>
|
||
|
||
<p>Compile the file using a standard C compiler (note we’re linking to
|
||
<code class="code">libecl.so</code> with <code class="code">-lecl</code>, which provides the lisp
|
||
runtime<a class="footnote" id="DOCF3" href="System-building.html#FOOT3"><sup>3</sup></a>):
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">gcc test.c example-with-dep--all-systems.so -o test -lecl
|
||
</pre></div>
|
||
|
||
<p>If ECL is installed in a non-standard location you may need to provide
|
||
flags for the compiler and the linker. You may read them with:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">ecl-config --cflags
|
||
ecl-config --libs
|
||
</pre></div>
|
||
|
||
<p>Since our shared object is not in the standard location, you need to
|
||
provide <code class="code">LD_LIBRARY_PATH</code> pointing to the current directory to
|
||
run the application:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">LD_LIBRARY_PATH=`pwd` ./test
|
||
</pre></div>
|
||
|
||
<p>This will show:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">Factorial of 5 is: 120
|
||
</pre></div>
|
||
|
||
<p>You can also build all dependent libraries separately as a few
|
||
<code class="code">.so</code> files and link them together. For example, if you are
|
||
building a library called <code class="code">complex-example</code>, that depends on
|
||
<code class="code">alexandria</code> and <code class="code">cl-fad</code>, you can do the following (in the
|
||
REPL):
|
||
</p>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">(asdf:make-build :complex-example
|
||
:type :shared-library
|
||
:move-here #P"./"
|
||
:init-name "init_example")
|
||
|
||
(asdf:make-build :alexandria
|
||
:type :shared-library
|
||
:move-here #P"./"
|
||
:init-name "init_alexandria")
|
||
|
||
(asdf:make-build :cl-fad
|
||
:type :shared-library
|
||
:move-here #P"./"
|
||
:init-name "init_fad")
|
||
|
||
(asdf:make-build :bordeaux-threads
|
||
:type :shared-library
|
||
:move-here #P"./"
|
||
:init-name "init_bt")
|
||
</pre></div>
|
||
|
||
<p>Note that we haven’t specified <code class="code">:monolithic t</code>, so we need to build
|
||
<code class="code">bordeaux-threads</code> as well because <code class="code">cl-fad</code> depends on it. The
|
||
building sequence doesn’t matter and the resultant <code class="code">.so</code> files can
|
||
also be used in your future programs if these libraries are not
|
||
modified.
|
||
</p>
|
||
<p>We need to initialize all these modules using <code class="code"><a class="ref" href="System-building.html#ecl_005finit_005fmodule">ecl_init_module</a></code>
|
||
in the correct order. (<code class="code">bordeaux-threads</code> must be initialized
|
||
before <code class="code">cl-fad</code>; <code class="code">cl-fad</code> and <code class="code">alexandria</code> must be
|
||
initialized before <code class="code">complex-ecample</code>.)
|
||
</p>
|
||
<p>Here is a code snippet (not a full program):
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">extern void init_fad(cl_object);
|
||
extern void init_alexandria(cl_object);
|
||
extern void init_bt(cl_object);
|
||
extern void init_example(cl_object);
|
||
|
||
/* call these *after* cl_boot(argc, argv);
|
||
if B depends on A, you should first init A then B. */
|
||
ecl_init_module(NULL, init_bt);
|
||
ecl_init_module(NULL, init_fad);
|
||
ecl_init_module(NULL, init_alexandria);
|
||
ecl_init_module(NULL, init_example);
|
||
</pre></div>
|
||
|
||
<hr>
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Build-it-as-static-library-and-use-in-C">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Previous: <a href="System-building.html#Build-it-as-shared-library-and-use-in-C" accesskey="p" rel="prev">Build it as shared library and use in C</a>, Up: <a href="System-building.html#Compiling-with-ASDF" accesskey="u" rel="up">Compiling with ASDF</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsubsection" id="Build-it-as-static-library-and-use-in-C-1">3.1.2.4 Build it as static library and use in C</h4>
|
||
|
||
<p>To build a static library, use:
|
||
</p>
|
||
<div class="example lisp">
|
||
<pre class="lisp-preformatted">(asdf:make-build :example-with-dep
|
||
:type :static-library
|
||
:move-here #P"./"
|
||
:monolithic t
|
||
:init-name "init_example")
|
||
</pre></div>
|
||
|
||
<p>This will generate <code class="code">example-with-dep--all-systems.a</code> in the
|
||
current directory which we need to initialize with the
|
||
<code class="code">init_example</code> function. Compile it using:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">gcc test.c example-with-dep--all-systems.a -o test-static -lecl
|
||
</pre></div>
|
||
|
||
<p>Then run it:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">./test-static
|
||
</pre></div>
|
||
|
||
<p>This will show:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example-preformatted">Factorial of 5 is: 120
|
||
</pre></div>
|
||
|
||
<p>Note we don’t need to pass the current path in <code class="code">LD_LIBRARY_PATH</code>
|
||
here, since our Lisp library is statically bundled with the executable.
|
||
The result is the same as the shared library example above. You can also
|
||
build all dependent libraries separately as static libraries.
|
||
</p>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="subsection-level-extent" id="C-compiler-configuration">
|
||
<div class="nav-panel">
|
||
<p>
|
||
Previous: <a href="System-building.html#Compiling-with-ASDF" accesskey="p" rel="prev">Compiling with ASDF</a>, Up: <a href="System-building.html#System-building" accesskey="u" rel="up">System building</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<h4 class="subsection" id="C-compiler-configuration-1">3.1.3 C compiler configuration</h4>
|
||
|
||
<p>ECL provides some global variables to customize which C compiler and
|
||
compiler options to use:
|
||
</p>
|
||
<ul class="mini-toc">
|
||
<li><a href="System-building.html#Compiler-flags" accesskey="1">Compiler flags</a></li>
|
||
<li><a href="System-building.html#Compiler-_0026-Linker-programs" accesskey="2">Compiler & Linker programs</a></li>
|
||
</ul>
|
||
<div class="subsubsection-level-extent" id="Compiler-flags">
|
||
<h4 class="subsubsection">3.1.3.1 Compiler flags</h4>
|
||
|
||
<p>It is not required to surround the compiler flags with quotes or use
|
||
slashes before special characters.
|
||
</p>
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_002auser_002dcc_002dflags_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c:*user-cc-flags*</strong><a class="copiable-link" href='System-building.html#index-c_003a_002auser_002dcc_002dflags_002a'> ¶</a></span></dt>
|
||
<dd><p>Flags and options to be passed to the C compiler when building FASL,
|
||
shared libraries and standalone programs.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_002auser_002dlinker_002dflags_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c:*user-linker-flags*</strong><a class="copiable-link" href='System-building.html#index-c_003a_002auser_002dlinker_002dflags_002a'> ¶</a></span></dt>
|
||
<dd><p>Flags for options (e.g. <code class="code">-Wl,foo</code> flags, usually in the
|
||
<code class="code">$LDFLAGS</code> variable in autoconf) to be passed to the linker when
|
||
building FASL, shared libraries and standalone programs.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_002auser_002dlinker_002dlibs_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c:*user-linker-libs*</strong><a class="copiable-link" href='System-building.html#index-c_003a_002auser_002dlinker_002dlibs_002a'> ¶</a></span></dt>
|
||
<dd><p>Flags for libraries (e.g. <code class="code">-lfoo</code> flags, usually in the
|
||
<code class="code">$LIBS</code> variable in autoconf) to be passed to the linker when
|
||
building FASL, shared libraries and standalone programs.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_002acc_002doptimize_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c:*cc-optimize*</strong><a class="copiable-link" href='System-building.html#index-c_003a_002acc_002doptimize_002a'> ¶</a></span></dt>
|
||
<dd><p>Optimize options to be passed to the C compiler.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_002auser_002dld_002dflags_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c:*user-ld-flags*</strong><a class="copiable-link" href='System-building.html#index-c_003a_002auser_002dld_002dflags_002a'> ¶</a></span></dt>
|
||
<dd><p><strong class="strong">DEPRECATED</strong> Flags and options to be passed to the linker when
|
||
building FASL, shared libraries and standalone programs.
|
||
</p></dd></dl>
|
||
|
||
</div>
|
||
<div class="subsubsection-level-extent" id="Compiler-_0026-Linker-programs">
|
||
<h4 class="subsubsection">3.1.3.2 Compiler & Linker programs</h4>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_003a_002acc_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c::*cc*</strong><a class="copiable-link" href='System-building.html#index-c_003a_003a_002acc_002a'> ¶</a></span></dt>
|
||
<dd><p>This variable controls how the C compiler is invoked by ECL. One can
|
||
set the variable appropriately adding for instance flags which the C
|
||
compiler may need to exploit special hardware features (e.g. a
|
||
floating point coprocessor).
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_003a_002ald_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c::*ld*</strong><a class="copiable-link" href='System-building.html#index-c_003a_003a_002ald_002a'> ¶</a></span></dt>
|
||
<dd><p>This variable controls the linker which is used by ECL.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_003a_002aranlib_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c::*ranlib*</strong><a class="copiable-link" href='System-building.html#index-c_003a_003a_002aranlib_002a'> ¶</a></span></dt>
|
||
<dd><p>Name of the ‘ranlib’ program on the hosting platform.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_003a_002aar_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c::*ar*</strong><a class="copiable-link" href='System-building.html#index-c_003a_003a_002aar_002a'> ¶</a></span></dt>
|
||
<dd><p>Name of the ‘ar’ program on the hosting platform.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_003a_002aecl_002dinclude_002ddirectory_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c::*ecl-include-directory*</strong><a class="copiable-link" href='System-building.html#index-c_003a_003a_002aecl_002dinclude_002ddirectory_002a'> ¶</a></span></dt>
|
||
<dd><p>Directory where the ECL header files for the target platform are located.
|
||
</p></dd></dl>
|
||
|
||
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
|
||
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-c_003a_003a_002aecl_002dlibrary_002ddirectory_002a"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">c::*ecl-library-directory*</strong><a class="copiable-link" href='System-building.html#index-c_003a_003a_002aecl_002dlibrary_002ddirectory_002a'> ¶</a></span></dt>
|
||
<dd><p>Directory where the ECL library files for the target platform are located.
|
||
</p></dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="footnotes-segment">
|
||
<hr>
|
||
<h4 class="footnotes-heading">Footnotes</h4>
|
||
|
||
<h5 class="footnote-body-heading"><a id="FOOT3" href="System-building.html#DOCF3">(3)</a></h5>
|
||
<p>You may also link ECL runtime statically. That is not
|
||
covered in this walkthrough.</p>
|
||
</div>
|
||
<hr>
|
||
<div class="nav-panel">
|
||
<p>
|
||
Next: <a href="Operating-System-Interface.html#Operating-System-Interface" accesskey="n" rel="next">Operating System Interface</a>, Up: <a href="Extensions.html" accesskey="u" rel="up">Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
|
||
|
||
|
||
</body>
|
||
</html>
|