Installation

You can get the metanorma command-line executable by installing this Ruby gem.

Important

To install the Metanorma toolchain we recommend to use one of the ways described in Metanorma installation topic. Installing this gem by hand may not be the easiest way.

When following this installation method, to start building documents you may have to take care of manually installing some required third-party software as well. Which exactly depends on what documents you’re building, below notes cover some of that.

Installing the Metanorma CLI gem

gem install metanorma-cli

Installing the gem will also install all officially supported Metanorma flavors (such as ISO, CalConnect, IETF, etc).

Dependencies

The Metanorma toolchain (the one you install as Metanorma-CLI) is dependent on ruby-xslt.

ruby-xslt, in its turn, depends on the native libraries: libxml2 and libxslt.

You can install those using conventional package managers under Linux and macOS.

  • Linux: yum on CentOS, apt on Debian/Ubuntu, dnf on Fedora

  • macOS: Homebrew

For Windows, read below.

Puppeteer

If you are going to generate PDFs from HTML (which applies to CalConnect Standard Documents), you will also need to install the Puppeteer Node library.

PlantUML

If your documents include PlantUML diagrams, PlantUML will have to be installed.

  • brew install plantuml on MacOS.

  • For Linux, link the PlantUML jar file into a command line executable; see .travis.yml for an example.

If PlantUML is not installed locally, the source PlantUML is incorporated into the output document as sourcecode.

Installation notes for Windows

The Metanorma toolchain (the one you install as metanorma-cli) is dependent on ruby-xslt.

ruby-xslt, in its turn, depends on the native libraries: libxml2 and libxslt.

To satisfy this dependency on Windows, you need to:

  1. Get native libraries (libxml2 and libxslt) compiled for your architecture (x86 for 32-bit or x64 for 64-bit Windows)

  2. Provide right options during gem build

  3. Ensure these native libraries are accessible at run-time (of the Metanorma toolchain)

Installing the native libraries (prerequisites)

Here we have two option:

  • Build from source code (difficult)

  • Get pre-built binaries (easy)

We go with the latter because it is faster and less error-prone.

The pre-built binaries can be installed via the Chocolatey package manager on Windows.

  1. Installing Chocolatey is straightforward: follow instructions at https://chocolatey.org/install

  2. Then, both libxml2 and libxslt can be installed by running this command

cinst xsltproc

Once this is done, the necessary libraries/headers are installed in the %ChocolateyInstall%\lib\xsltproc\dist directory.

Installing the gems

Here there are also two options:

  • Using the gem command

  • Using the bundle command

Note
Before running this step you must have already installed the prerequisite libraries stated above.

Installing the gem manually via gem

The commands are given below.

gem install ruby-xslt -- ^
	--with-xml2-include=%ChocolateyInstall%\lib\xsltproc\dist\include\libxml2 ^
	--with-xslt-include=%ChocolateyInstall%\lib\xsltproc\dist\include ^
	--with-xml2-lib=%ChocolateyInstall%\lib\xsltproc\dist\lib ^
	--with-xslt-lib=%ChocolateyInstall%\lib\xsltproc\dist\lib

Installing the gem via bundle

Note
Before running this step you must have already installed the prerequisite libraries stated above.
bundle config build.ruby-xslt ^
	--with-xml2-include=%ChocolateyInstall%\lib\xsltproc\dist\include\libxml2 ^
	--with-xslt-include=%ChocolateyInstall%\lib\xsltproc\dist\include ^
	--with-xml2-lib=%ChocolateyInstall%\lib\xsltproc\dist\lib ^
	--with-xslt-lib=%ChocolateyInstall%\lib\xsltproc\dist\lib
bundle install

Success message

With both methods of installing the gem, you should see the following output without any errors.

Fetching ruby-xslt X.X.XX
Installing ruby-xslt X.X.XX with native extensions

Ensuring the native libraries are available at run-time

Step 1: General

Firstly, the ruby-xslt gem expects the names of libxml2 and libxslt library files to not have the version numbers in filenames.

We need to ‘strip’ away the version numbers from the DLL files using the following commands:

xcopy /y %ChocolateyInstall%\lib\xsltproc\dist\bin\libxml2*.dll %ChocolateyInstall%\lib\xsltproc\dist\bin\libxml2.dll*
xcopy /y %ChocolateyInstall%\lib\xsltproc\dist\bin\libxslt*.dll %ChocolateyInstall%\lib\xsltproc\dist\bin\libxslt.dll*
xcopy /y %ChocolateyInstall%\lib\xsltproc\dist\bin\libexslt*.dll %ChocolateyInstall%\lib\xsltproc\dist\bin\libexslt.dll*

Step 2: If Ruby version >= 2.4.1

In Ruby versions newer than 2.4.1, we can use RUBY_DLL_PATH environment variable to set the correct Ruby DLL path.

This can be accomplished this by running the following one-time command in PowerShell or cmd:

setx /m RUBY_DLL_PATH "%ChocolateyInstall%\lib\xsltproc\dist\bin;%RUBY_DLL_PATH%"
Note
The setx command stores this change in the registry and therefore the configuration will persist upon restarts.

Step 2: If Ruby version < 2.4.1

Prior to Ruby 2.4.1, the native libraries must be copied to the Ruby bin directory to be available for the Ruby runtime as follows (in PowerShell or cmd):

xcopy /y %ChocolateyInstall%\lib\xsltproc\dist\bin\lib*.dll C:\Ruby25\bin*
Note
This is also a one-time change that persists across restarts.

Installation completed!

If you got here following the instructions step by step, you have set up Metanorma on Windows successfully—congratulations!