Chapter 36. 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

36.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 36.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.

36.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).

36.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 36.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.

36.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 36.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.

36.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 36.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.

36.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’)