Chapter 23. LogiQL Project

When you are first exploring LogiQL, you are most often adding and executing small pieces of logic into the workspace through the LogicBlox command-line interface. As you build more complex logic that evolves into an application, it is useful to be able to organize your logic into files, and files into projects that represent self-contained units of functionality.

LogicBlox provides support for creating, compiling, and distributing projects as libraries. This chapter describes the basic structure of projects, their compilation and use.

23.1. Project Structure

A LogicBlox project has two components:

  • a project description file;
  • a directory, possibly with subdirectories, containing the logic files of the project.

The project description file specifies the LogiQL files and modules, libraries, and protocol buffer messages that must be compiled as parts of this project. A project description must be contained in a file whose name ends with the extension .project.

The project description file follows a simple comma-delimited format. Apart from proto directives (see Section 22.1.2, “Importing the Protocol Message Specification”), each line is of the following form:

<name>, <type indicator>
<name>

Name of the item. For files and modules it can be either an absolute path or the path relative to the directory containing the project description file. Even though an absolute path is allowed, all files must be contained within the same directory as the project description file, or in subdirectories of that directory.

<type indicator>

The type of the name. The following values are allowed:

projectname

Used to specify the name of the project. Project names must be valid LogiQL identifiers.

active

For installed blocks.

inactive

For stored queries.

inactiveAfterFixpoint

For stored queries intended to be activated after the end of stage FINAL.

execute

The file will be compiled, and will be executed when the project is installed into a workspace.

module

Indicates that the name on the first field is that of a directory containing LogiQL modules.

library

Indicates that the name on the first field is that of a library. The name of the library is the same as the project name specified in the library's project description file. The environment variable LB_LIBRARY_PATH, or, alternatively, the command line option -libPath can be used to specify a path of directories to be recursively searched for libraries. By default, the $LOGICBLOX_HOME/BlockResources directory is always included in the search for libraries.

severities

Severity declarations for various error codes. There can be only one severities declaration file per project. The severity declarations in the severities file apply to all logic in a project. It is possible for individual logic files to increase the project-wide severity declaration; however, an individual logic file cannot decrease a project-wide severity.

To change the severity level of a code from its default to a different level of severity, you can use the following four types of declarations in the severities file (CODE should be replaced by a concrete error code reported by the compiler):

// do not report CODE at all
lang:compiler:disableWarning:CODE[] = true.

// report CODE as a warning only
lang:compiler:disableError:CODE[] = true.

// report CODE as an error
lang:compiler:error:CODE[] = true.

// report CODE as a warning
lang:compiler:warning:CODE[] = true.

The project file can contain whitespace, which is ignored by the compiler. It can also contain comments: a comment is a complete line that begins with two forward slashes (//).

The entries are specified in the required order of compilation, with the programmer managing the compilation dependencies for non-module code. For example, the following project file separately compiles a library, some legacy files and a module directory:

// This is a comment
// This specifies that this project is named example
example, projectname
system:baseBootstrap,library

// An active legacy-code block
b1.logic, active

// This is a directory containing modules
employees, module

b2.logic,active
b3.logic,active

The compiler will compile entries in the project description file in the order they are specified in the file. This is also the order in which logic will be installed and executed, except for

  • libraries, which are always installed before other logic;
  • directories that contain module code: the correct ordering is determined automatically from the dependencies within the modules.

23.2. Compiling a Project

A project described in file myproject.project can be compiled on Unix/Mac with the following command:

$ lb compile project myproject.project

There are a number of options associated with the command lb compile project. Detailed descriptions can be found in Section 33.5.4, “lb compile project”. You can also retrieve usage information with the following command:

$ lb compile project --help

Compiling a project in this manner can improve the development cycle in two ways. First, disassociating the compilation of logic from the creation/addition of logic into a live workspace leads to faster response times. Secondly, the separate compilation mechanism supports incremental compilation: a file is recompiled only when necessary, i.e., when it is changed or when it depends on a changed file.

If there are no compilation errors, the compilation step produces a bytecode file filename.lbb for each logic file filename.lb. Additionally, it also produces a summary file called LB_SUMMARY. Each bytecode file is generated in the same directory as the corresponding source file, unless the --out-dir option is used.

Compilation is incremental, and is guided by a number of heuristics:

  • If any of the libraries referenced by the project has changed, that is, its timestamp is newer than the time the project was last compiled, the entire project must be recompiled.
  • An individual source file F is recompiled according to the following rules:
    1. If a clean build is specified, F is recompiled, as are all the other source files in this project.
    2. If there is no associated bytecode file, F is recompiled.
    3. If the associated bytecode file is older than F, F is recompiled.
    4. If a predicate compiled in another file has changed after the most recent compilation of F, and the existing bytecode file for F indicates that the file references that predicate, then F is recompiled.

When the compiler is invoked with the --explain option, it will provide information on why it makes certain decisions about incremental compilation.

23.3. Installing a Project

Once the project has been compiled, the following command can be used to install the project into a workspace (you should, of course, substitute appropriate names for workspace-name and directory-name):

$ lb addproject workspace-name directory-name

directory-name should be the output directory of the compiled project. Note that if a library is referenced by the project, and that library has not already been installed, the library will be searched for. If it is found, it will be installed; if it is not found, installation will fail. $LOGICBLOX_HOME/BlockResources will always be searched. Optionally, additional directories will be searched if the LB_LIBRARY_PATH environment variable is set, or the --libpath command line option is given.