@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

98 lines (92 loc) • 22.1 kB

HTML

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>The standalone command-line compiler — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="DevEnv.html">↑</a><a class="lpdoc-navbutton" href="builder_doc.html">←</a><a class="lpdoc-navbutton" href="ciao-shell.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a></span><span><a href="ciaofulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> »<br/> </li><li><a href="DevEnv.html">PART I - The program development environment</a> »<br/> </li><li><a href=""><strong>The standalone command-line compiler</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Introduction to building executables">Introduction to building executables</a></li><li><a href="#Running executables from the command line">Running executables from the command line</a></li><li><a href="#Types of executables generated">Types of executables generated</a></li><li><a href="#Intermediate files in the compilation process">Intermediate files in the compilation process</a></li><li><a href="#Usage (ciaoc)">Usage (ciaoc)</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>The standalone command-line compiler</h1> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="The Ciao Development Team" href="ciaosearch.html#The Ciao Development Team">The Ciao Development Team</a>.<p> <a class="lpdoc-idx-anchor" id="0" href="ciaosearch.html#compiling, from command line"></a> <a class="lpdoc-idx-anchor" id="1" href="ciaosearch.html#compiler, standalone"></a> <a class="lpdoc-idx-anchor" id="2" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> [<a class="lpdoc-idx-anchor" id="3" href="ciaorefs.html#ciaoc-entcs">CH00b</a>] is the Ciao standalone command-line compiler. <a class="lpdoc-idx-anchor" id="4" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> can be used to create executables or to compile individual files to object code (to be later linked with other files). <a class="lpdoc-idx-anchor" id="5" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> is specially useful when working from the command line. Also, it can be called to compile Ciao programs from other tools such as, e.g., <a class="lpdoc-idx-anchor" id="6" href="ciaosearch.html#shell scripts">shell scripts</a>, <a class="lpdoc-idx-anchor" id="7" href="ciaosearch.html#Makefile"><tt>Makefile</tt></a>s, or <a class="lpdoc-idx-anchor" id="8" href="ciaosearch.html#project files">project files</a>. All the capabilities of <a class="lpdoc-idx-anchor" id="9" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> are also available from the interactive top-level shell, which uses the <a class="lpdoc-idx-anchor" id="10" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> modules as its components.<p><div id="Introduction to building executables"><h2>Introduction to building executables</h2> <p>An <a class="lpdoc-idx-anchor" id="11" href="ciaosearch.html#executable"><em>executable</em></a> can be built from a single file or from a collection of inter-related files. In the case of only one file, this file must define the predicate <a class="lpdoc-idx-anchor" id="12" href="ciaosearch.html#main/0"><tt>main/0</tt></a> or <a class="lpdoc-idx-anchor" id="13" href="ciaosearch.html#main/1"><tt>main/1</tt></a>. This predicate is the one which will be called when the executable is started. As an example, consider the following file, called <tt>hello.pl</tt>:<p><pre class="lpdoc-codeblock">main :- write('Hello world'), nl. </pre> <p>To compile it from the command line using the <a class="lpdoc-idx-anchor" id="14" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> standalone compiler it suffices to type ``<tt>ciaoc hello</tt>'' (in Win32 you may have to put the complete path to the <a class="lpdoc-idx-anchor" id="15" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> folder of the Ciao distribution, where the installation process leaves a <a class="lpdoc-idx-anchor" id="16" href="ciaosearch.html#ciaoc.bat"><tt>ciaoc.bat</tt></a> file):<p><pre class="lpdoc-codeblock">$ ciaoc hello </pre> <p>This produces an executable called <tt>hello</tt> in Unix systems and <tt>hello.cpx</tt> under Win32 systems. This executable can then be run in Win32 by double-clicking on it and on Unix systems by simply typing its name (see <a href="#Running executables from the command line">Running executables from the command line</a> for how to run executables from the command line in Win32):<p><pre class="lpdoc-codeblock">$ ./hello Hello world </pre> <p>If the application is composed of several files the process is identical. Assume <tt>hello.pl</tt> is now:<p><pre class="lpdoc-codeblock">:- use_module(aux, [p/1]). main :- p(X), write(X), nl. </pre> <p>where the file <tt>aux.pl</tt> contains:<p><pre class="lpdoc-codeblock">:- module(aux,[p/1]). p('Hello world'). </pre> <p>This can again be compiled using the <a class="lpdoc-idx-anchor" id="17" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> standalone compiler as before:<p><pre class="lpdoc-codeblock">$ ciaoc hello $ ./hello Hello world </pre> <p>The invocation of <tt>ciaoc hello</tt> compiles the file <tt>hello.pl</tt> and all connected files that may need recompilation -- in this case the file <tt>aux.pl</tt>. Also, if any library files used had not been compiled previously they would be compiled at this point (See <a href="#Intermediate files in the compilation process">Intermediate files in the compilation process</a>). Also, if, say, <tt>hello.pl</tt> is changed and recompiled, the object code resulting from the previous compilation of <tt>aux.pl</tt> will be reused. This is all done without any need for <tt>Makefile</tt>s, and considerably accelerates the development process for large applications. This process can be observed by selecting the <tt>-v</tt> option when invoking <tt>ciaoc</tt> (which is equivalent to setting the <tt>verbose_compilation</tt> Prolog flag to <tt>on</tt> in the top-level interpreter).<p>If <a class="lpdoc-idx-anchor" id="18" href="ciaosearch.html#main/1"><tt>main/1</tt></a> is defined instead of <a class="lpdoc-idx-anchor" id="19" href="ciaosearch.html#main/0"><tt>main/0</tt></a> then when the executable is started the argument of <a class="lpdoc-idx-anchor" id="20" href="ciaosearch.html#main/1"><tt>main/1</tt></a> will be instantiated to a list of atoms, each one of them corresponding to a command line option. Consider the file <tt>say.pl</tt>:<p><pre class="lpdoc-codeblock">main(Argv) :- write_list(Argv), nl. write_list([]). write_list([Arg|Args]) :- write(Arg), write(' '), write_list(Args). </pre> <p>Compiling this program and running it results in the following output:<p><pre class="lpdoc-codeblock">$ ciaoc say $ ./say hello dolly hello dolly </pre> <p>The name of the generated executable can be controlled with the <tt>-o</tt> option (See <a href="#Usage (ciaoc)">Usage (ciaoc)</a>).<p></div><div id="Running executables from the command line"><h2>Running executables from the command line</h2> <a class="lpdoc-idx-anchor" id="21" href="ciaosearch.html#executables, how to run"></a> <p>As mentioned before, what the <tt>ciaoc</tt> compiler generates and how it is started varies somewhat from OS to OS. In general, the product of compiling an application with <tt>ciaoc</tt> is a file that contains the bytecode (the product of the compilation) and invokes the <a class="lpdoc-idx-anchor" id="22" href="ciaosearch.html#Ciao engine">Ciao engine</a> on it.<p><ul> <p><li>In Unix this is a <em>script</em> (see the first lines of the file) which invokes the ciao engine on this file. To run the generated executable from a Unix shell it suffices to type its name at the shell command line, as in the examples above.<p><li>In a Win32 system, the compiler produces a similar file with a <tt>.cpx</tt> ending and an additional <tt>.bat</tt> file.<p>The Ciao installation process typically makes sure that the Windows registry contains the right entries so that <tt>.cpx</tt> executables will run upon double-clicking and from a command shell (in NT systems).<p>The <tt>.bat</tt> files allow running the Ciao executable from any other processes (which typically does not use the Windows registry).<p>Finally, in a system in which Cygwin is installed, executables can also be used directly from the <a class="lpdoc-idx-anchor" id="23" href="ciaosearch.html#bash"><tt>bash</tt></a> shell command line, without any associated <tt>.bat</tt> files, by simply typing their name at the <a class="lpdoc-idx-anchor" id="24" href="ciaosearch.html#bash"><tt>bash</tt></a> shell command line, in the same way as in Unix.<p></ul> <p>Except for a couple of header lines, the contents of executables are almost identical under different OSs (except for self-contained ones). The bytecode they contain is architecture-independent. In fact, it is possible to create an executable under Unix and run it on Windows or viceversa, by making only minor modifications (e.g., creating the <tt>.bat</tt> file and/or setting environment variables or editing the start of the file to point to the correct engine location).<p></div><div id="Types of executables generated"><h2>Types of executables generated</h2> <p><a class="lpdoc-idx-anchor" id="25" href="ciaosearch.html#executables, types"></a> <p>While the default options used by <a class="lpdoc-idx-anchor" id="26" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> are sufficient for normal use, by selecting other options <a class="lpdoc-idx-anchor" id="27" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> can generate several different types of executables, which offer interesting tradeoffs among size of the generated executable, portability, and startup time [<a class="lpdoc-idx-anchor" id="28" href="ciaorefs.html#ciaoc-entcs">CH00b</a>]:<p><dl> <p><dt>Dynamic executables:<dd> <a class="lpdoc-idx-anchor" id="29" href="ciaosearch.html#executables, dynamic"></a> <p><a class="lpdoc-idx-anchor" id="30" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> produces by default <em>dynamic</em> executables. In this case the executable produced is a <a class="lpdoc-idx-anchor" id="31" href="ciaosearch.html#platform-independent">platform-independent</a> file which includes in compiled form all the user defined files. On the other hand, any system libraries used by the application are loaded dynamically at startup. More precisely, any files that appear as <tt>library(...)</tt> in <a class="lpdoc-idx-anchor" id="32" href="toplevel_doc.html#use_module/1"><tt>use_module/1</tt></a> and <a class="lpdoc-idx-anchor" id="33" href="toplevel_doc.html#ensure_loaded/1"><tt>ensure_loaded/1</tt></a> declarations will not be included explicitly in the executable and will instead be loaded dynamically. Is is also possible to mark other <a class="lpdoc-idx-anchor" id="34" href="ciaosearch.html#path aliases">path aliases</a> (see the documentation for <a class="lpdoc-idx-anchor" id="35" href="stream_basic.html#file_search_path/2"><tt>file_search_path/2</tt></a>) for dynamic loading by using the <tt>-d</tt> option. Files accessed through such aliases will also be loaded dynamically.<p>Dynamic loading allows making smaller executables. Such executables may be used directly in the same machine in which they were compiled, since suitable paths to the location of the libraries will be included as default in the executable by <a class="lpdoc-idx-anchor" id="36" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a> during compilation.<p>The executable can also be used in another machine, even if the architecture and OS are different. The requirement is that the Ciao libraries (which will also include the appropriate <a class="lpdoc-idx-anchor" id="37" href="ciaosearch.html#Ciao engine">Ciao engine</a> for that architecture and OS) be installed in the target machine, and that environment variables are set appropriately for the executable to be able to find them (see <a href="Install.html#Environment variables used by Ciao executables">Environment variables used by Ciao executables</a>). How to do this differs slightly from OS to OS.<p><dt>Static executables:<dd> <a class="lpdoc-idx-anchor" id="38" href="ciaosearch.html#executables, static"></a> <p>Selecting the <tt>-s</tt> option <tt>ciaoc</tt> produces a <em>static</em> executable. In this case the executable produced (again a <a class="lpdoc-idx-anchor" id="39" href="ciaosearch.html#platform-independent">platform-independent</a> file) will include in it all the auxiliary files and any system libraries needed by the application. Thus, such an executable is almost complete, needing in order to run only the <a class="lpdoc-idx-anchor" id="40" href="ciaosearch.html#Ciao engine">Ciao engine</a>, which is platform-specific.<p><b>Note:</b> Currently there is an exception to this related to libraries which are written in languages other than Prolog, as, e.g., C. C files are currently always compiled to dynamically loadable object files (<tt>.so</tt> files), and they thus need to be included manually in a distribution of an application. This will be automated in upcoming versions of the Ciao system.<p> Again, if the executable is run in the same machine in which it was compiled then the engine is found automatically. If the executable is moved to another machine, the executable only needs access to a suitable engine (which can be done by setting the appropriate environment variables, see <a href="Install.html#Environment variables used by Ciao executables">Environment variables used by Ciao executables</a>).<p>This type of compilation produces larger executables, but has the advantage that these executables can be installed and run in a different machine, with different architecture and OS, even if Ciao is not installed on that machine. To install (or distribute) such an executable, one only needs to copy the executable file itself and the appropriate engine for the target platform (See <a href="Install.html">Installing Ciao from the source distribution</a> or <span class="lpdoc-missing">Installing Ciao from a Win32 binary distribution</span> and <a href="Install.html#Multiarchitecture installation">Multiarchitecture installation</a>), and to set things so that the executable can find the engine. <p><b>Note:</b> It is also possible to produce real standalone executables, i.e., executables that do not need to have an engine around. However, this is not automated yet, although it is planned for an upcoming version of the compiler. In particular, the compiler can generate a <tt>.c</tt> file for each <tt>.pl</tt> file. Then all the <tt>.c</tt> files can be compiled together into a real executable (the engine is added one more element during link time) producing a complete executable for a given architecture. The downside of course is that such an executable will not be portable to other architectures without recompilation.<p> <p><dt>Dynamic executables, with lazy loading:<dd> <a class="lpdoc-idx-anchor" id="41" href="ciaosearch.html#executables, lazy load"></a> <p>Selecting the <tt>-l</tt> option is very similar to the case of dynamic executables above, except that the code in the library modules is not loaded when the program is started but rather it is done during execution, the first time a predicate defined in that file is called. This is advantageous if a large application is composed of many parts but is such that typically only some of the parts are used in each invocation. An executable with lazy load has the advantage that it starts fast, loading a minimal functionality on startup, and then loads the different modules automatically as needed.<p><dt>Self-contained executables:<dd> <a class="lpdoc-idx-anchor" id="42" href="ciaosearch.html#executables, self-contained"></a> <p><em>Self-contained</em> executables are static executables (i.e., this option also implies <em>static</em> compilation) which include a Ciao engine along with the bytecode, so they do not depend on an external one for their execution. This is useful to create executables which run even if the machine where the program is to be executed does not have a Ciao engine installed and/or libraries. The disadvantage is that such execuatbles are <a class="lpdoc-idx-anchor" id="43" href="ciaosearch.html#platform-dependent">platform-dependent</a> (as well as larger than those that simply use an external library). This type of compilation is selected with the <tt>-S</tt> option. Cross-compilation is also possible with the <tt>-SS</tt> option, so you can specify the target OS and architecture. To be able to use the latter option, it is necessary to have installed a <tt>ciaoengine</tt> for the target machine in the Ciao library (this requires compiling the engine in that OS/architecture and installing it, so that it is available in the library).<p></dl> <p></div><div id="Intermediate files in the compilation process"><h2>Intermediate files in the compilation process</h2> <p>Compiling an individual source (i.e., <tt>.pl</tt>) file produces a <tt>.itf</tt> file and a <tt>.po</tt> file. The <tt>.itf</tt> file contains information of the <a class="lpdoc-idx-anchor" id="44" href="ciaosearch.html#modular interface"><em>modular interface</em></a> of the file, such as information on exported and imported predicates and on the other modules used by this module. This information is used to know if a given file should be recompiled at a given point in time and also to be able to detect more errors statically including undefined predicates, mismatches on predicate charaterictics across modules, etc. The <tt>.po</tt> file contains the platform-independent object code for a file, ready for linking (statically or dynamically).<p>It is also possible to use <tt>ciaoc</tt> to explicitly generate the <tt>.po</tt> file for one or more <tt>.pl</tt> files by using the <tt>-c</tt> option.<p>If you want to view the WAM instructions of one or more <tt>.pl</tt> files you can use the <tt>-w</tt> option. That will generate a <tt>.wam</tt> file with such instructions in a pretty format per each <tt>.pl</tt> file.<p></div><div id="Usage (ciaoc)"><h2>Usage (ciaoc)</h2> <p>The following provides details on the different command line options available when invoking <a class="lpdoc-idx-anchor" id="45" href="ciaosearch.html#ciaoc"><tt>ciaoc</tt></a>:<p><p> <p><pre class="lpdoc-codeblock"> ciaoc [Opts] <Files> Compile the listed files. If there is more than one file, the first one is considered the main module (it must include the main predicate when creating an executable). The default extension for files is '.pl'. -h, --help Show this help. -u <File> Use File for compilation, often used to include LibDir paths, etc. --iso-strict Turn on stricter ISO compatibility for user files and modules declared with module/2. -op <Suffix> Use Suffix as the suffix for optimized (or otherwise tuned) code. -L <LibDir> Look for libraries also in the LibDir directory. -c Generate .po objects for the input modules. -w Generate .wam files (WAM code) for the input modules. -S Make standalone executable for the current OS and architecture, implies -s. -SS <EngCfg> Make standalone executable for the EngCfg OS and architecture (and optionally debugging level) (see ciao_sysconf for valid values for Target), implies -s. -ll <Module> Force Module to be loaded lazily, implies -l. -ac <Packages> Use Packages for compiling all modules. -acm <Module> <Packages> Use the given Packages (term) for compiling Module. -d <Path> Files using this path alias are dynamic (default: library). -o <File> Specify output file name. -v, --verbose-compilation Verbose mode. -ri, --itf-format-r Generate human-readable .itf files. -x, --check-libraries Check for changes also in the Ciao standard library during incremental compilation (for developers). -s, --executables-static Make a static executable (otherwise dynamic files are not included). -l, --executables-lazyload Idem with lazy load of dynamic files (except insecure cases). -np, --use-global-module-options-no Ignore global module options. -na, --read-assertions-no Do not read the assertions in the code. -rc, --runtime-checks Generate code with runtime checks; requires reading assertions. --rtchecks-trust-no Disable rtchecks for trust assertions. --rtchecks-entry-no Disable rtchecks for entry assertions. --rtchecks-exit-no Disable rtchecks for exit assertions. --rtchecks-test Enable rtchecks for test assertions (for debugging purposes only, unittest library is recommended). --rtchecks-level-exports Use rtchecks only for external calls of the exported predicates. --rtchecks-asrloc-no Do not use assertion locators in the error messages. --rtchecks-predloc-no Do not use predicate locators in the error messages. --rtchecks-namefmt-short Show the name of predicates and properties in a reduced format. --rtchecks-callloc-no Do not show the stack of predicates that caused the failure. --rtchecks-callloc-literal Show the stack of predicates that caused the failure. Instrument it in the literal. This mode provides more information, because reports also the literal in the body of the predicate. </pre> </div><br/></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>