Chapter 38. The LB Configuration Tool
The LB configuration tool can be used to configure a
Makefile for building, testing,
and installing LogiQL projects and libraries. Once you have
created a config.py file that declares the
projects, libraries, dependencies, workspaces, and tests for a
project, running lb config will
generate a new Makefile.
In most cases, the following commands will compile the project, run tests, and install any files when applicable:
make ## compile make check ## run tests make install ## install make dist ## generate source distribution
38.1. Creating config.py
The config.py script is fundamentally a Python
script, but its
code is intended to be in declarative style, declaring the
libraries, workspaces, and test targets.
The following is an example of a config.py script
that declares a
LogicBlox library and a workspace in which that library will be installed:
Example 38.1. An example configuration script
from lbconfig.api import *
lbconfig_package(
'my-app-name',
default_prefix = '/opt/logicblox/my-app',
default_targets = ['foo', 'bar'])
depends_on(
logicblox_dep,
jacoco = '/path/to/jacoco',
guava = {'default_path': '/path/to/guava', '
help' = 'Description for this parameter'})
lb_library(
name = 'my-lb-project',
srcdir = 'logiql/my-lb-project',
srcgen = ['my_protobuf_message_proto.logic'],
deps = ['lb-web']
)
check_lb_workspace(
name = 'my-workspace'
libraries = ['my-lb-project']
)The first thing to note is that all public functions are imported from lbconfig. Next the package metadata, its dependencies, the LogicBlox library and the workspace are declared. Since this is done in a declarative way, the order in which these are defined does not change the outcome of the build.
The above functions are described in the following sections. For a detailed overview of all of the supported functions, please refer to the lbconfig API documentation.
38.1.1. lbconfig_package
The lbconfig_package function is used to
declare some of the package’s metadata, such as its
name and default installation directory. It is also used to set
the default targets.
By default, the installation directory is the local
out directory. This can be changed by using the
default_location
parameter in lbconfig_package.
To set an installation directory when configuring the build, use
the --prefix command line argument:
lb config --prefix /install/here
We will further refer to the installation prefix as
$(prefix).
38.1.2. depends_on
Parts of a project are often dependent on other resources. For
instance,
a LogicBlox library might depend on other LogicBlox libraries,
Java files or JARs. In the case of
Example 38.1, “An example configuration script”, the LogicBlox library
my-lb-project depends on lb-web (see the
deps parameter in the invocation of
lb_library).
To declare dependencies in the LB configuration tool, the
depends_on function can be used as shown in the
example.
lbconfig.api has two predefined dependencies
that can be used: logicblox_dep and
lb_web_dep. Other dependencies can be added
by listing them as named parameters of other functions, as the example
shows.
For each declared dependency, the LB configuration tool will
create a variable in the Makefile. As a result,
we
can refer to
the guava path with $(guava). The tool will also
create command line arguments to
lb config, so that
the path for each dependency can be changed. For our example,
the lb config command
will accept a --with-guava parameter. Here is how to
configure the build for a different path:
lb config --with-guava=/some/other/path/to/guava
Finally, declaring dependencies will cause a check that all of the paths exist. If they do not, the build will not proceed.
38.1.3. lb_library
The lb_library function is used to declare a
LogiQL project that should be compiled and installed into
$(prefix).
In Example 38.1, “An example configuration script”, a
project named my-lb-project is compiled in the
logiql/my-lb-project directory. The name of
the library is the name of the project file, without the
.project extension.
The srcgen parameter specifies the source
files that have been generated, such as protobuf, LogiQL, Java,
or Python files. Since these file are generated from other
files, they need not and will not be included in source
distributions.
By default, make install will cause
lb_library to install the
compiled project in $(prefix).
For a library that does not
have to be installed, such as libraries for testing purposes,
one should use the check_lb_library function
instead, which takes similar parameters.
38.1.4. check_lb_workspace
The check_lb_workspace function is used to
declare a workspace that should be built by
make check.
In Example 38.1, “An example configuration script”, the workspace
is named my-workspace and
the my-lb-project library is installed into the
workspace.
The LB configuration tool creates the following
make targets for dealing with
workspaces:
check-lb-workspaces-
Will create all workspaces declared in
config.py. check-ws-foobar-
Will create the workspace declared with the name
foobar.
38.2. Extending the LB configuration tool
Extensions to the current functions of the LB configuration tool or
new functions should be defined in a file called
lbconfig_local.py.
lbconfig_local.py:
def my_special_rule(foo, bar):
. . .
config.py:
from lbconfig.api import * from lbconfig_local import * my_special_rule(‘foo’, ‘bar’)