Documentation
  • Introduction
  • Why Ampersand?
    • The Business Rules Manifesto and Ampersand
  • Tutorial
    • Example system: Enrollment
    • Conceptual Model: Enrollment
    • Your tool: RAP4
    • Making your first Ampersand script
  • Reactive programming
  • The language Ampersand
    • How to read syntax statements
    • Truth
    • Atoms
    • The CONCEPT statement
    • The RELATION statement
    • The MEANING statement
    • The PURPOSE statement
    • The CLASSIFY statement
    • The RULE statement
    • Terms
      • Semantics
      • Semantics in logic
        • Primitive terms
        • Boolean operators
        • Relational operators
        • Residual operators
      • Semantics in natural language
        • Primitive terms in natural language
        • Boolean operators in natural language
        • Relational operators in natural language
        • Residual operators in natural language
      • Semantics in sets
        • Primitive terms in set theory
        • Boolean operators in set theory
        • Relational operators in set theory
      • Semantics of terms, defined algebraically
        • Boolean operators in algebra
        • Relational operators in algebra
      • Semantics visualized
        • Semantics of boolean operators visualized
        • Semantics of relational operators visualized
        • Semantics of residuals visualized
    • Context
    • Module
    • Best Practices
    • Syntactical Conventions
      • The CONCEPT statement
      • The RELATION statement
      • The RULE statement
      • The CONTEXT statement
      • The INCLUDE statement
      • Explanation
      • Patterns
      • Population
        • Population in spreadsheets
      • The PURPOSE statement
      • The IDENT statement
      • The TABLE statement
      • Language support
    • The INCLUDE statement
    • Patterns
    • Services
      • Example: Client
      • Example: Login
      • Syntax and meaning
      • Explanation
      • Layout of user interfaces
        • Your own widgets (HTML and CSS)
      • CRUD
    • Population
      • Population in spreadsheets
    • The ENFORCE statement
    • The IDENT statement
    • The TABLE statement
    • Language support
    • Current date
    • The Preprocessor
    • Design considerations
  • Running the Ampersand compiler
    • Configuration
    • Commands (vs. 4.0.0 and later)
    • Options (up to vs. 3.17.4)
  • Architecture of an Ampersand Application
    • Backend framework
    • Hooks
    • Extensions
      • The ExecEngine
  • Deploying your Ampersand script
    • Compiler
    • Deploy your own web application on your laptop
    • Prototype multi-stage build
    • Prototype database
  • Reusing Available Modules
    • Modules
    • Security
    • SIAM (Sessions, Identity and Access Management) Module
  • Exercises
    • Delivery
    • VOG (in Dutch)
  • Installing Ampersand
    • Deploying your Prototype
    • Installing the tools manually
  • Modeling
    • Domain Driven Design
    • Data modeling
    • Legal modeling
    • Architecture modeling
    • Metamodeling
    • Limitations of Ampersand
  • Configuring your application
  • The Excel Importer
  • Plans
    • Current State
    • NoSQL storage
    • API documentation
    • OWL and RDFS input
    • Refactor the front-end
  • Research
Powered by GitBook
On this page
  • Purpose
  • Prerequisites
  • COMMAND
  • SYNOPSIS
  • DESCRIPTION
  • Environment variables
  • EXAMPLES
  • BUGS
  • Exit status
Export as PDF

Running the Ampersand compiler

If you want to check your script, generate documentation, generate prototypes or use any other feature of Ampersand, you need to run the Ampersand compiler. This page tells you how.

PreviousDesign considerationsNextConfiguration

Last updated 3 years ago

Purpose

In many situations, you can avoid running the Ampersand compiler from the command line. For instance, by using a system such as . However, in situations that you run Ampersand from the command line, this page is the place to be.

Prerequisites

We assume you have docker running on your computer and that you are connected to the internet. In that case you don't have to install anything.

COMMAND

The following is the base command on Linux (works for bash as well as zsh)

docker run -it -v $(pwd):/scripts ampersandtarski/ampersand

On the Windows-10 command-line this looks slightly different (todo: check this!)

docker run -it -v $PWD:/scripts ampersandtarski/ampersand

This runs the Ampersand compiler (from your command prompt). The first time you do this, docker will take some time to download the images it needs.

SYNOPSIS

docker run -it -v "$(pwd)":/scripts ampersandtarski/ampersand COMMAND [OPTIONS] FILE

In the sequel we will use ampersand as an alias for docker run -it -v "$(pwd)":/scripts ampersandtarski/ampersand

DESCRIPTION

Environment variables

The standard behavior of ampersand is affected by the following environment variables.

  • CCdbName Sets the name of the database that is to be generated. Can be overruled by --dbName

  • CCdirOutput Sets the default output directory for generated assets. Can be overruled by --outputDir

  • CCdirPrototype Sets the default directory where functional prototypes are being generated. Can be overruled by --proto

EXAMPLES

ampersand documentation --format docx --verbose Hawaii.adl  # generates a specification document for Hawaii.adl
ampersand check Delivery.adl                                # just check Delivery.adl for errors
ampersand proto --proto-dir "D:\htdocs\CvM\" Contracts.adl  # generate a prototype from Contracts.adl and write the application to the specified directory.
ampersand --help
ampersand --help --verbose
ampersand --version

BUGS

Exit status

Code

Name

Meaning

0

Success

Compilation has terminated without failures

2

Fatal

10

Invalid

The script is not valid and the compiler has produced error messages to help you diagnose your mistake(s).

20

Inconsistent

The population would violate invariants. The compiler cannot generate a violation-free database.

30

Invalid SQL

50

Ampersand violations

There are sanity checks on your script that have produced violations, so the compiler will not generate an application.

60

Composer

The installation of Composer failed, so the front-end application will not work. This is most likely a configuration error.

70

Wrong arguments

The command-line arguments by which the compiler was called contain errors. Inspect the compiler output for a diagnosis.

80

Back-end

The compiler failed to install the prototype framework. This is most likely a configuration error.

The command ampersand takes a file as input. It must contain a valid ampersand script, i.e. a script that complies to the and semantics of ampersand. The compiler will not generate any output unless the script is valid.

We are happy to receive . However, please try to help us by first checking that it has not been reported already. You can do so by searching the issues. When in doubt however, don't hesitate to .

In case the Ampersand compiler is called by software and fails, it is useful to have an exit code to give some information about the nature of the failure. The Ampersand compiler :

This is a software error in the Ampersand compiler, that should never have occured in operational use. Please .

An SQL query gives other results than the semantics of Ampersand prescribes. This should never occur, so please .

RAP
syntax
bug reports at AmpersandTarski
create a new issue
produces the following exit codes
report an issue
report an issue