This file is part of Logtalk https://logtalk.org/
SPDX-FileCopyrightText: 1998-2023 Paulo Moura [email protected]
SPDX-License-Identifier: Apache-2.0
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
This directory contains sample scripts for selected backend Prolog
compilers for embedding Logtalk and Logtalk applications. See the
SCRIPT.txt
file for usage examples.
These scripts allow pre-compilation of the Logtalk compiler/runtime and optionally of a Logtalk application. This is a common requirement for embedding, specially when deploying applications in read-only file systems. These sample scripts should be regarded as starting points as actual use often requires customization (e.g. the starting goal, inclusion of a top-level interpreter, etc).
An alternative, available in some backend Prolog compilers such as
SICStus Prolog, SWI-Prolog, and YAP, is to create a saved state
after loading Logtalk and a Logtalk application (or the generated
Prolog code for Logtalk and a Logtalk application). Saved states
are usually executable files that embed both a Prolog runtime and
application code. See the SCRIPT.txt
file for some examples.
For details on creating and using saved states, see your backend
Prolog compiler documentation.
Note that the provided scripts don't handle applications composed of both Logtalk and Prolog source files. In these cases, either move (if possible) the Prolog code into Logtalk source files or customize the embedding scripts to include the contents of the Prolog files into the generated embedding files.
On POSIX systems, the scripts require the Bash shell.
On Windows, experimental PowerShell scripts are available for selected backends. Using the PowerShell scripts may require first changing the execution policy:
PowerShell.exe -ExecutionPolicy Unrestricted
In alternative, a possible solution to run the Bash shell scripts is to
install either the Windows Subsystem for Linux (WSL)
or Git for Windows. Both provide access
to a Bash shell. In both cases, use full paths with forward slashes
(e.g. C:/Users/jdoe/collect
) and without environment variables. You
must also specify the temporary directory for intermediate files using
the scripts -t
option. Also, symbolic links may not work and use of
actual paths to files may be required.
The scripts accept a command-line option for specifying a settings file.
See the settings-embedding-sample.lgt
file for settings suggestions for
embedding applications. Notably, the reload
flag should usually be set
to skip
to prevent reloading of already loaded code when running the
embedded application or saved state. You may also want to turn off the
source_data
flag to reduce the size of your application. When a settings
file is passed as argument to the embedding scripts, the backend adapter
file ia automatically patched, changing the value of the settings_file
flag to deny
, to prevent using any settings file accessible on a computer
where the embedded application is run to disturb it.
It's also possible to not include any settings file by using the -s none
option. This is mostly useful when generating a new top-level executable
that only includes the Logtalk compiler/runtime.
The scripts also accept a command-line option for specifying a paths file.
This paths file must provide definitions for the logtalk_library_path/2
predicate for all libraries loaded by the application being embedded. The
following query can be used to find the names of all the libraries used
by a loaded application:
| ?- setof(Library, File^(logtalk::loaded_file_property(File, library(Library))), Libraries).
To help ensure that the embedded application is relocatable, load it and verify that the following query fails:
| ?- setof(Library, File^(logtalk::loaded_file_property(File, library(Library))), Libraries),
member(Missing, Libraries),
\+ logtalk_library_path(Missing, _).
To avoid dependencies on the Logtalk LOGTALKHOME
and LOGTALKUSER
environment variables, the sample scripts support an option for
expanding library aliases paths in the paths and settings files. This
option also allows (in general) the safe inclusion of the application
loader files. If for some reason this option is not desirable, the
embedded application or saved state should be run in a process that
sets (possibly just for itself) the LOGTALKHOME
and LOGTALKUSER
environment variables to the values used during the pre-compilation
of the Logtalk resources. For example, in a POSIX system, you can
use something like:
$ LOGTALKHOME=/usr/local/share/logtalk LOGTALKUSER=/home/user/logtalk ./saved_state
The Bash version of the embedding scripts use GNU sed
when available.
Notably on macOS, if you get sed
errors when running the embedding
scripts, try installing GNU sed
(using e.g. Homebrew or MacPorts).