Build profiles

It is common to be simultaneously working with different versions of a website, each of which needs to be built in slightly different ways. A common scenario is to have a local version of the site so that you can test it on your own machine, and a production version that is deployed to a server. In Salal, build profiles are used to store information about how to build and deploy the site in each case.

Build profiles are placed in a JSON-format configuration file called config/project_config.json. Here is a sample of the basic file structure for the scenario where you need test and production profiles. For clarity we just show the tree structure, not the full JSON syntax:

common
|---system
|---project
test
|---system
|---project
production
|---system
|---project

The common section is optional. Any configuration information you place in it will be used as a default value for all profiles. If you specify a value in both the common section and in a specific profile, the value from the specific profile will be used.

The first section in the file other than common will be treated as the default profile. This is the profile that will be used if you run Salal without explicitly specifying a profile.

Within each section of the file, you can have a system subsection and a project subsection. Both are optional. The system subsection is for variables that control how Salal operates. The project subsection is for variables that you want available to the templating engine as your site is being built. A brief example will help illustrate the typical use of each.

You may have a set of templates, CSS styles, or other design elements that you'd like to be able to use on multiple sites. Salal supports that through the use of Themes. You tell Salal to use a particular theme for your project by defining a system variable theme_root, which points to the directory where the theme files can be found:

common
|---system
    |---paths
        |---theme_root: /home/mario/my_themes/cool_design"

Turning to project variables, suppose you have a Python backend for your site. As part of that, you have several Python scripts that are run to handle requests coming in from the client. These scripts need to indicate where the Python interpreter can be found. And it's in a different location on the test machine and on the server. That can be handled with a project variable. First, put a variable reference in your script files:

#!{{project.python_path}}

Then, specify the appropriate path for each profile in your project config file:

test
|---project
    |---python_path: C:/msys64/mingw64/bin/python.exe
production
|---project
    |---python_path: /home/sally/opt/python-3.6.2/bin/python3

This technique can also be used for building web pages, CSS, JavaScript scripts, or any other kind of file where you've configured Salal to do variable substitution. And it can sometimes be useful even when the value is consistent across profiles. For example, suppose all pages of a particular type should load a given CSS file. You could hard-code the URL for the CSS file in your page template. However, it may be better for maintainability to use a project variable instead. You can put something like this in your template:

<link rel="stylesheet" href="{{project.special_style_file}}" type="text/css" />

And then put this in your project config file:

common
|---project
    |---special_style_file: /css/style_for_sally.css