4 Konffaa

6.5

← prev up next →

4 Konffaa

Tero Hasu

Konffaa is a lightweight configuration manager originally created for the ContextLogger2 project. Konffaa aims to work with different build managers and scripts by generating build information in different languages. It consists of a konffaa command-line tool and a konffaa project configuration specification language.

4.1 Variant Specification Language

#lang konffaa

package: konffaa

The konffaa language exports all of racket, as well as additional forms for defining variants and their attributes.

For defining a variant, you may use the define-variant, define-variant*, and define-variant** forms. The one-star form is like the no-star form, except that it provides the defined variant. The two-star form both provides the variant under its original name, plus it also provides it as the “main” import of the module, so that the konffaa command will find it.

syntax
(define-variant id (base-expr ...) body ...+)
syntax
(define-variant* id (base-expr ...) body ...+)
syntax
(define-variant** id (base-expr ...) body ...+)

Defines a product variant, binding it as id. The variant inherits from other variants as specified by base-expr .... The body ... of a definition should contain attributes, fields, and axioms specifying the variant and its constraints.

syntax
(define-attribute id value-expr ...+)
syntax
(define-field id value-expr ...+)

Defines a variant attribute or field, naming it as id. Its value is given by the last of the value-expressions. The difference between the two forms is that only the former defines fields whose values get output; consequently, those values should be serializable. Inheritance works for both kinds of fields.

syntax
(define-axiom id assert-expr ...+)

Defines an axiom, naming it as id. The assert-expressions would typically contain one or more assertions. Axioms can be inherited between variants in the same way as fields are.

syntax
(assert test-expr maybe-msg)

maybe-msg =
| message

An assertion to use within an axiom. An optional message may be provided, in addition to a test-expression which should hold for the containing axiom to hold.

See the source code of the modules "attribute.rkt", "axiom.rkt", and "surface.rkt" for more details about the konffaa DSL.

For examples of variant configuration files, see the "variants" directory of the source distribution.

4.2 Command-Line Interface

The idea with configuring a project for a specific build variant with Konffaa is simple: you invoke konffaa for a specific configuration variant as its command-line argument:

konffaa variant

The variant may either name a variant specification file, or it may be a variant name, whose filename is then assumed to be "variants/variant.var.rkt".

When correctly invoked, the konffaa program will then process the specified variant-describing input file by computing a full set of attributes for that variant, which—if the associated axioms hold—are then output essentially as sets of key-value pairs in different file formats. Those output files will then reflect the selected variant configuration until such time that konffaa is invoked again to choose a different configuration.

The generated include files are only touched when they actually change as a result of the change in configuration, which allows Konffaa to work better with build managers (such as Make) whose dependency checking is based on timestamps.

The generated include files are intended to be used to configure other development tools (most notably build managers) in a variant-specific way.

Konffaa presently supports GNU Make and qmake as foreign output languages, as well as C and Ruby, with the latter ones aimed at configuring programs and custom build scripts. Scripts can be particularly useful for driving template-based generation of input files for more obscure build tools that use non-standard file formats.

4.3 Shell Completion

Completion of variant names based on the ".var.rkt" suffixed files found in the "variants" directory is supported for the konffaa command in the Bash shell. That support is provided by the "bash_completion" file in the source distribution.

4.4 License

Except where otherwise noted, the following license applies:

Authors: Tero Hasu

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

← prev up next →

1	Magnolisp
2	Illusyn
3	Erda
4	Konffaa

4.1	Variant Specification Language
4.2	Command-Line Interface
4.3	Shell Completion
4.4	License