@ciao-lang/ts-ciao-interface
Version:
Simple Ciao interface for node.
39 lines (38 loc) • 11.3 kB
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>Bundle management — 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="debugger.html">←</a><a class="lpdoc-navbutton" href="ciaoc.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>Bundle management</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Setting up workspaces">Setting up workspaces</a></li><li><a href="#Using and creating bundles">Using and creating bundles</a></li><li><a href="#Workspaces during Ciao bootstrap">Workspaces during Ciao bootstrap</a></li><li><a href="#Generating binary distributions">Generating binary distributions</a></li><ul><li><a href="#Adding assets to binary distributions">Adding assets to binary distributions</a></li></ul><li><a href="#Troubleshooting">Troubleshooting</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Bundle management</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#builder"></a>
<strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Jose F. Morales" href="ciaosearch.html#Jose F. Morales">Jose F. Morales</a>, <a class="lpdoc-idx-anchor" id="The Ciao Development Team" href="ciaosearch.html#The Ciao Development Team">The Ciao Development Team</a>.<p>
The <a class="lpdoc-idx-anchor" id="0" href="ciaosearch.html#ciao"><tt>ciao</tt></a> command implements most bundle management operations. The most important commands are:<p><pre class="lpdoc-codeblock">$ ciao list # List bundles in current workspaces
$ ciao build [<tgts>] # Build
$ ciao build -r [<tgts>] # Build, including dependencies
$ ciao fetch [<tgts>] # Fetch all dependencies of a bundle
$ ciao get [<tgts>] # Fetch, build, and install a bundle
$ ciao rm [<tgts>] # Remove a bundle
</pre> <p>Most commands accept one ore more targets (workspace paths, bundle directories, bundle names, or bundle aliases for location on the network). For example, valid targets are: <ul> <li>(empty) (in which case Ciao locates the bundle above the current directory) <li>bundle names (e.g., <tt>chat80</tt>) <li>paths to bundles (e.g., <tt>~/ciao/chat80</tt>) <li>URL-like aliases to bundles (e.g., <tt>github.com/jfmc/chat80</tt>, where <tt>chat80</tt> is the bundle name) </ul> <p>Execute <tt>ciao help</tt> to obtain a detailed list of commands.<p><div id="Setting up workspaces"><h2>Setting up workspaces</h2> <p>Ciao locates bundles by looking at one or more workspaces, given by the following (optional) environment variables:<p><ul> <li><tt>CIAOPATH</tt>: colon-separated list of paths to individual workspaces <li><tt>CIAOROOT</tt>: the root directory of this Ciao installation (either in binary or source form) </ul> <p>Workspaces from <tt>CIAOPATH</tt> are consulted from left to right. If <tt>CIAOPATH</tt> is undefined, a default value of <tt>~/.ciao</tt> will be used. The first encountered workspace directory is denoted as the <em>top</em> workspace. The variable <tt>CIAOROOT</tt> is usually not needed, except when the binaries is being relocated on the filesystem.<p><div class="lpdoc-note"> <strong>Note:</strong> <tt>CIAOPATH</tt> should not point to <tt>CIAOROOT</tt> (it is not needed and it may produce inconsistent builds). </div> <p>As mentioned in <a href="Install.html#Full installation instructions">Full installation instructions</a>, setting up the environment uses the <a class="lpdoc-idx-anchor" id="1" href="ciaosearch.html#ciao-env"><tt>ciao-env</tt></a> tool, which updates the <tt>PATH</tt> and other environment variables to make commands and documentation (<tt>man</tt>, <tt>info</tt>) accessible by default.<p><strong>Configuring workspaces:</strong> The directory <tt>~/ciao</tt> can be added permanently as a workspace as follows. Include the following at the <tt>~/.emacs</tt> file:<p><pre class="lpdoc-codeblock">(setenv "CIAOPATH" (expand-file-name "~/ciao"))
</pre> <p>Then add these lines to the <tt>~/.bashrc</tt> file: <pre class="lpdoc-codeblock">export CIAOPATH=~/ciao
</pre> <p>It is possible to change <tt>CIAOPATH</tt> temporarily from <tt>emacs</tt> (<tt>M-x setenv</tt>) or a shell in a terminal (executing <tt>export CIAOPATH=<path></tt>)<p></div><div id="Using and creating bundles"><h2>Using and creating bundles</h2> <p><strong>Creating new bundles:</strong> For creating new bundles it is recommended to define a workspace directory (e.g., <tt>~/ciao</tt>) and set the <span class="lpdoc-var">CIAOPATH</span> environment variable to that directory.<p>Bundles can be created from scratch or cloned from repositories, e.g.: <pre class="lpdoc-codeblock">$ cd ~/ciao
$ git clone https://github.com/jfmc/chat80
</pre> <p>At that point bundles can be managed with the <a class="lpdoc-idx-anchor" id="2" href="ciaosearch.html#ciao"><tt>ciao</tt></a> command. The <tt>ciao list</tt> should display <tt>chat80</tt> as a recognized bundle, and it should be possible to configure, build, or install it (e.g., <tt>ciao build</tt> at <tt>chat80</tt> directory or <tt>ciao build chat80</tt> anywhere). Most commands will rescan the bundles at the workspace, but it can be done manually with: <pre class="lpdoc-codeblock">$ ciao rescan-bundles
</pre> Note that existing toplevels may need to be restarted to recognize modules at the new bundles.<p><strong>Network installation:</strong> It is possible to download, configure, build, and install automatically bundles from the network. For example: <pre class="lpdoc-codeblock">ciao get github.com/jfmc/chat80
</pre> will fetch and install <tt>chat80</tt> under the top workspace (<tt>~/.ciao</tt> if <tt>CIAOPATH</tt> is unset) (see <a class="lpdoc-idx-anchor" id="3" href="ciaosearch.html#bundle_fetch"><tt>bundle_fetch</tt></a>). The bundle name will be <tt>chat80</tt>, while the rest of the bundle alias is used to locate the location on the network. The command: <pre class="lpdoc-codeblock">ciao rm chat80
</pre> removes the bundle (to prevent accidental data losses, only iff it has been marked as <em>downloaded</em>).<p></div><div id="Workspaces during Ciao bootstrap"><h2>Workspaces during Ciao bootstrap</h2> <p><p>In the context of calls to <tt><srcdir>/ciao-boot.sh</tt>, <tt>CIAOROOT</tt> is implicitly set to the directory where <tt>ciao-boot.sh</tt> is located (<tt><srcdir></tt>) and <tt>CIAOPATH</tt> is unset. Thus only bundles at <tt><srcdir></tt> (including bundle <em>catalog</em> directories) are considered.<p>This is useful to:<p><ul> <li>prevent existing <tt>CIAOPATH</tt> values interact with system builds <li>fetch bundles during system build (e.g., the <tt>devenv</tt> bundle) </ul> <p><strong>Example:</strong> the following command will bootstrap Ciao from source, as well as fetch and install the full development environment:<p><pre class="lpdoc-codeblock">./ciao-boot.sh get devenv
</pre> <p></div><div id="Generating binary distributions"><h2>Generating binary distributions</h2> <p>The <a class="lpdoc-idx-anchor" id="4" href="ciaosearch.html#ciaoc_sdyn"><tt>ciaoc_sdyn</tt></a> command can be used to generate binary distributions of executables with complex dependencies, including any 3rd-party dynamic libraries.<p>Example: <pre class="lpdoc-codeblock">mkdir dist; cd dist
ciaoc_sdyn ../src/YOURMAINEXEC
cp ../src/SOMEASSET
</pre> <p>This creates a platform specific binary YOURMAINEXEC at <tt>dist/</tt> directory, together with the collection of shared libraries for the dependencies.<p><div class="lpdoc-alert"> Copying <tt>.so</tt> or <tt>.dynlib</tt> that corresponds to system libraries are not a good idea. To fix the issue the following command can be used: <pre class="lpdoc-codeblock">rm -f libc.so.* libgcc_s.so.* libm.so.* libstdc++.so.*
</pre> </div> <p><div id="Adding assets to binary distributions"><h3>Adding assets to binary distributions</h3> <p>The <a class="lpdoc-idx-anchor" id="5" href="ciaosearch.html#bundle_path/3"><tt>bundle_path/3</tt></a> predicate (at <a class="lpdoc-idx-anchor" id="6" href="ciaosearch.html#bundle/bundle_paths"><tt>bundle/bundle_paths</tt></a>) can be used to obtain the absolute path name of a bundle or a relative path in a bundle.<p>Example:<p><pre class="lpdoc-codeblock">:- use_module(library(system), [file_exists/1]).
:- use_module(library(pathnames), [path_concat/3]).
:- use_module(library(bundle/bundle_paths), [bundle_path/3]).
% Find file X in the same directory as the executable
% or in the sources.
find_asset(Name, Path) :-
( current_executable(ExecPath),
path_split(ExecPath, Dir, _)
; bundle_path(<SomeBundle>, 'images', Dir)
),
path_concat(Dir, Name, Path0),
file_exists(Path0),
!,
Path = Path0.
</pre> <p>The example predicate <tt>find_assert/2</tt> above will look for arbitrary files in either the <tt>images/</tt> directory or the directory of the current executable.<p><pre class="lpdoc-codeblock">find_asset('spaceship.png', Sprite)
</pre> <p></div></div><div id="Troubleshooting"><h2>Troubleshooting</h2> <p><strong>Q:</strong> Changing the (workspace) directory of a bundle.<p><strong>A:</strong> It would be enough to rescan bundles and configure (clean and build is recommended too). Go to the workspace and type the following:<p><pre class="lpdoc-codeblock">ciao rescan-bundles
ciao configure [<configuration-options>]
</pre> <p><strong>Q:</strong> Compilation of some module complains about missing dependencies (to seemingly auto-generated code and third-party libraries).<p><strong>A:</strong> Make sure that the bundle and its dependencies are properly configured and build (e.g., calling <tt>ciao build</tt> for each of them or with <tt>ciao build -r</tt>). Some bundles (e.g., interfaces to external solvers) require pre-build steps to download and compile third-party code. This part of the compilation is not currently handled by the Ciao compiler.<p><strong>Q:</strong> Alias paths configured at <tt>.ciaorc</tt> are not visible in executables.<p><strong>A:</strong> The <tt>.ciaorc</tt> file is read only by the Ciao toplevel (not arbitrary Ciao executables). Configure <a class="lpdoc-idx-anchor" id="7" href="ciaosearch.html#alias path">alias path</a>s through manifest files instead.<p></div><br/></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>