Different Ways To Get/Use RIDDL

There are several ways to get riddl software on to your computer, depending on how you want to work.

Download

This is the simplest way to get riddlc. It should run on Windows, Mac and Linux. Follow these steps:

Go to the riddlc downloads page
Click on the release title you want to install
Scroll down to the “Assets” section
Download the riddlc-{version}.zip file
Unzip that file on your computer
Place the riddlc-{version}/bin directory in your path

Staged

To use riddlc locally and be able to update it with new changes without a large download, use this approach:

git clone https://github.com/ossuminc/riddl.git
cd riddl
Put the ./riddlc/target/universal/stage/bin directory in your PATH variable using a full path instead of “.”
Run sbt stage to build the program
To update, run git pull from the riddl cloned repository directory and rerun sbt stage to rebuild.

This allows you to both make local changes and pull in changes from others to keep your local copy of riddlc up to date.

Integrate With SBT

TBD.

RiddlSbtPlugin

To use the sdt-plugin you must first have installed riddlc by one of the above methods. This approach allows you to run riddlc commands from a sbt based project. The command you configure will run first when you use the compile command in sbt. Follow these steps:

In your plugins.sbt file, add: `addSbtPlugin(“com.ossuminc” % “sbt-riddl” % “{version}”). You can find the latest available version here
In your build.sbt file, use enablePlugins(SbtRiddlPlugin) on your project
Set the following sbt settings:
- riddlcPath := file("...") This defaults to “riddlc” which is appropriate if the right version is in your path; otherwise specify the full path to the riddlc command
- riddlcOptions := Seq("from", "path/to/config/file", "hugo") This is just an example, you can put any command or options you want in that sequence. Use riddlc help to find out what commands you can use.
To run a translator in this way, put a riddlc.conf file next to the top level .riddl file you want to translate. The content of that file can specify common options and the commands you want to support from sbt-riddl, like the example below, taken from the riddl-examples project. These files use Human-Oriented-CONfiguration

common {
    show-times = true
    verbose = true
    quiet = false
    dry-run = false
    show-warnings = true
    show-missing-warnings = false
    show-style-warnings = false
}
hugo {
    input-file = "ReactiveBBQ.riddl"
    output-dir = "target/hugo/ReactiveBBQ"
    project-name = "Reactive BBQ"
    site-title = "Reactive BBQ Generated Specification"
    site-description = "This site provides a specification for the Reactive BBQ application as generated by riddlc"
    site-logo-path = "images/RBBQ.png"
    erase-output = true
    base-url = "https://bbq.riddl.tech"
    source-url = "https://github.com/ossuminc/riddl"
    edit-path = "/-/blob/main/src/riddl/ReactiveBBQ"
}
validate {
    input-file = "ReactiveBBQ.riddl"