Did you know ... | Search Documentation: |
Packs with foreign code |
Many packs include C or C++ resources. Such packs include the C or
C++ resources in a subdirectory of the pack. There are no restrictions
for naming this subdirectory or structuring the source files in this
directory. The build process must create native modules in the
directory lib/<arch>
, where <arch>
is the architecture as obtained by the Prolog flag arch.
The build process identifies control files that tell the package
manager which build tool to use. The package manager populates the
process environment with variables that provide details about the
running Prolog instance. This environment is saved in a file buildenv.sh
in the pack root or build directory. By
sourcing this file, the user may run the build tools by hand
for debugging purposes.
The build process consists of five steps that are described below
conan
. It is executed if
either conanfile.txt
or conanfile.py
is found
in the root directory of the pack.CMakeLists.txt
(cmake), configure
, configure.in
(autoconf), configure.ac
or Makefile.am
(automake) are found. The program to
manage them is in parenthesis.Makefile
or
makefile
is expected and Unix make is used to build
the process.make check
.make install
.
While running the above tools, the environment is populated. The
names of the variables provided depends on the pack_version(Version)
metadata. We give the names for version 2, with the names for
version 1 in parenthesis if this differs from the version 2
name.
PATH
SWIPL
SWIPL_PACK_VERSION
SWIPL_VERSION
(SWIPLVERSION
)SWIPL_HOME_DIR
(SWIHOME
)SWIPL_ARCH
(SWIARCH
)SWIPL_MODULE_DIR
(PACKSODIR
)lib/$SWIARCH
.SWIPL_MODULE_LIB
(SWISOLIB
)SWIPL_LIB
(SWILIB
)-lswipl
)SWIPL_INCLUDE_DIRS
SWI-Prolog.h
, SWI-Stream.h
and
SWI-cpp2.h
.SWIPL_LIBRARIES_DIR
libswipl
SWIPL_CC
(CC
)SWIPL_CXX
(CXX
)SWIPL_LD
(LD
)SWIPL_CFLAGS
(CFLAGS
)-ISWIPL-INCLUDE-DIR
.SWIPL_MODULE_LDFLAGS
(LDSOFLAGS
)SWIPL_MODULE_EXT
(SOEXT
).so
or .dll
)SWIPL_PREFIX
(PREFIX
)
If the package requires some C code to be compiled that has no
dependencies and needs no configuration it is probably easiest to use a
simple Unix make file. We assume pack_version(2)
. Here is a
simple Makefile
. We assume the pack contains a file
c/environ.c
that contains the C source. Following the GNU
guidelines, the Makefile
must define the following targets:
distclean
target is used by pack_rebuild/1.MODULE= $(SWIPL_MODULE_DIR)/environ.$(SOEXT) CFLAGS= $(SWIPL_CFLAGS) all: $(MODULE) OBJ=c/environ.o $(MODULE): $(OBJ) mkdir -p $(SWIPL_MODULE_DIR) $(SWIPL_LD) $(SWIPL_MODULE_LDFLAGS) -o $@ $(OBJ) $(SWIPL_MODULE_LIB) check:: $(SWIPL) -g run_tests -t halt test/test_environ.pl install:: clean: rm -f $(OBJ) distclean: clean rm -f $(MODULE)
As described in section
15.4, a pack is distributed either as an archive file or as a GIT
repository. We strongly encourage using a GIT repository as that gives
good version and provenance support. Packs may be published by hand by
making the archive or git repository available from a globally
accessible place on the internet and installing the pack from this
location. This process is streamlined, notably for GIT packs using pack_publish/2
and the
app pack
. To publish a pack a local GIT repository
that has publicly accessible origin,
version(Version)
in pack.pl
swipl pack publish .
This will
download(URL)
metadata or the GIT remote information.Similarly, a pack can be published from a public archive using the command below. When using an archive, never change the content of the archive but, instead, create a new archive with a new version.
swipl pack publish URL
If the package is more complicated, a simple Makefile typically does not suffice. In this case we have two options. One is to use the GNU autoconf or automake. However, cmake is getting more popular and provides much better support for non-POSIX platforms, e.g., Windows. This section discusses building the same package as section 15.5.2.1 using cmake.
To use cmake, add the content below as the file
CMakeLists.txt
to the root directory of the pack.
SWI-Prolog ships with a cmake include file named
swipl.cmake
that deals with most of the configuration
issues. Comments in the file below explain the various steps of the
process.
cmake_minimum_required(VERSION 3.5) project(swipl-pack-environ) # Include swipl.cmake from the running SWI-Prolog's home list(INSERT CMAKE_MODULE_PATH 0 $ENV{SWIPL_HOME_DIR}/cmake) include(swipl) # Create the library as a CMake module add_library(environ MODULE c/environ.c) # Link the library to SWI-Prolog. This also removes the `lib` prefix # from the target on systems that define a common library file prefix target_link_swipl(environ) # Install the foreign taget. `${swipl_module_dir}` contains the # directory for installing modules for this architecture. install(TARGETS environ DESTINATION ${CMAKE_CURRENT_SOURCE_DIR}/${swipl_module_dir}) # Run tests. This is executed before the pack is installed. # swipl_test(name) runs Prolog with the command line below. # # swipl -p foreign=${CMAKE_CURRENT_SOURCE_DIR}/${swipl_module_dir} \ # -p library=${CMAKE_CURRENT_SOURCE_DIR}/prolog \ # --on-error=status \ # -g test_${name} \ # -t halt \ # ${CMAKE_CURRENT_SOURCE_DIR}/test/test_${name}.pl # # This implies that a test `name` must be defined in a file # `test/test_${name}.pl`, which exports a predicate `test_${name}`. The # test succeeds if this predicate succeeds and no error messages are # printed. enable_testing() swipl_add_test(environ)