Bootstrapp

The main purpose of the Bootstrapp application for macOS is to generate boilerplate for iOS and macOS apps and Swift packages from templates. However, the template system is general enough for just about any type of boilerplate generation.

License

The Bootstrapp app for macOS is released under the MIT license. See the LICENSE file in the repository for details.

However, Bootstrapp depends on other open source software (both first-party and third-party), subject to their own respective licenses. See the ATTRIBUTIONS file for details. Most notably, XcodeGen is used for generating Xcode project files and Splash is used for generating syntax highlighted Swift code.

Table of Contents

⚠️ This documentation is a work in progress.

• Installing Bootstrapp
  • System Requirements
  • Pre-built Binaries
• Using Bootstrapp
• Templates
  • Template Types
  • Structure of a Template
  • Bootstrapp.json
• Template Language
  • Substitutions
  • Conditionals
  • Conditional Expression
  • Loops
  • Longer Example

Installing Bootstrapp

Bootstrapp is a regular macOS app and is installed by dragging the app bundle to the /Applications folder, as usual.

System Requirements

Bootstrapp was built using SwiftUI, which requires macOS 10.15 Catalina or later.

Pre-built Binaries

With every release, a pre-built app binary along with some example templates will be attached to the assets section of the release entry here on GitHub.

Simply go to the releases page and expand the Assets section of the release you want to install. There you will find the Bootstrapp.app.zip and Templates.zip files. The app binary is signed for distribution and notarized by Apple.

Using Bootstrapp

Step 1: Drag a folder containing one or more templates onto the app window. The application will recursively look for any folder that contains a Bootstrapp.json file.

Step 2: Select a template in the sidebar on the left.

Step 3: Fill out the required fields of the form that appears.

Step 4: Press the hammer icon in the upper right corner to generate the boilerplate.

Templates

Template Types

There are three types of templates:

1. General
2. Swift Package
3. Xcode Project

General templates are not processed in any specific ways during the template instantiation. Files and folders will simply be copied from the Content/ folder to the output folder, only being subjected to parameter substitutions.

Swift Package templates are currently not processed in any specific ways either, but they may be in the future. Currently, the only difference is that they will be sorted in their own group in the sidebar and will be represented by a specific sidebar icon.

Xcode Project templates are processed just like the other templates with parameter substitutions, but they also contain an XcodeProject.yml file that specifies how the Xcode project file should be generated. The Xcode project file is generated by XcodeGen and the file format is thus the XcodeGen project specification file format.

Meta Templates

There are also templates for generating boilerplate for other templates. These are called Meta Templates. There's one meta template type per regular template type.

Structure of a Template

A Bootstrapp template has the following basic structure:

── Template/
    ├─ Bootstrapp.json
    ├─ Bootstrapp.md
    ├─ Content/
    │   ├─ <Any files / folders> 
    │   └─ [XcodeProject.yml]
    └─ Preview/
        ├─ 1.png
        ├─ 2.png
        ⋮
        └─ n.png

The main template specification is in the Bootstrapp.json file.

To provide information about the template, such as code examples or other documentation, add a Bootstrapp.md file. It will be shown in the Bootstrapp window for the template below the parameters form.

Any file or folder in the Content/ folder will be copied to the output folder as part of the generation process.

The Preview/ folder contains images (600x400 pixels) showcasing what the results will look like. In the case of an app template, it would be a good idea to use screenshots of the app, but any image can be used.

Bootstrapp.json

This is the main template specification file.

Top Level JSON Properties

Name	Value
specificationVersion	The version of the Bootstap.json file format itself, e.g. "1.0.0".
templateVersion	The version of this particular template, e.g. "1.0.0".
id	A unique identifier for this template. Also the name, for now.
type	One of "Swift Package", "Xcode Project", and "General".
description	A brief description of the template, shown at the top of the detail page.
outputDirectoryName	The name of the output directory. Not the path, just the directory name. Will be processed by substitution engine, e.g. "<{LIBRARY_NAME_}>".
substitutions	Non-user-configurable text substitutions as dictionary, e.g. ["DOT": "."]
parameters	User configurable text substitutions. Shown as form in template user interface.
parametrizableFiles	An array of regular expressions. File with names that match at least one of the regular expressions will be processed by the text substitution engine. Non-matching files will not.
includeDirectories	An array of conditions with expressions that when true will lead to the conditional inclusion of the specified directories. (Optional)
includeFiles	An array of conditions with expressions that when true will lead to the conditional inclusion of the specified files. (Optional)

Example: Swift Package Template

{
    "specificationVersion": "1.0.0",
    "templateVersion": "1.0.0",
    "id": "Library Swift Package",
    "type": "Swift Package",
    "description": "Use this template to quickly set up new static library Swift packages, complete with e.g. MIT license file, SwiftLint configuration, Jazzy documentation build script.",
    "outputDirectoryName": "<{LIBRARY_NAME}>",
    "substitutions": {
        "DOT": "."
    },
    "parameters": [ 
        {
            "name": "Library Name",
            "id": "LIBRARY_NAME",
            "type": "String",
            "validationRegex": "^[A-Za-z0-9_]+$"
        },
        {
            "name": "Copyright Holder",
            "id": "COPYRIGHT_HOLDER",
            "type": "String",
            "default": "Apparata AB"
        },
        {
            "name": "Docs Author URL",
            "id": "DOCS_AUTHOR_URL",
            "type": "String",
            "default": "https://apparata.se"
        },
        {
            "name": "License",
            "id": "LICENSE_TYPE",
            "type": "Option",
            "default": 0,
            "options": [
                "MIT",
                "BSD",
                "Apache 2",
                "Zlib",
                "Unlicense",
                "None"
            ]
        },
        {
            "name": "Add Executable Target",
            "id": "ADD_EXECUTABLE_TARGET",
            "type": "Bool",
            "default": false
        },
        {
            "name": "Executable Name",
            "id": "EXECUTABLE_NAME",
            "type": "String",
            "validationRegex": "^[A-Za-z0-9_]+$",
            "dependsOn": "ADD_EXECUTABLE_TARGET"
        },
        {
            "name": "Add GitHub test action",
            "id": "ADD_GITHUB_TEST_ACTION",
            "type": "Bool",
            "default": false
        },
        {
            "name": "Init git repo",
            "id": "GIT_INIT",
            "type": "Bool",
            "default": false
        }
    ],
    "parametrizableFiles": [
        "LICENSE",
        ".*\\.md",
        ".*\\.swift",
        ".*\\.h",
        ".*\\.m",
        ".*\\.mm",
        ".*\\.storyboard",
        ".*\\.xib",
        ".*\\.plist",
        ".*\\.json",
        ".*\\.yml",
        ".*\\.txt",
        ".*\\.sh"
    ],
    "includeDirectories": [
        {
            "if": "ADD_EXECUTABLE_TARGET",
            "directories": [
                "Sources/<{EXECUTABLE_NAME}>"
            ]
        },
        {
            "if": "ADD_GITHUB_TEST_ACTION",
            "directories": [
                "<{DOT}>github"
            ]
        },
        {
            "if": "GIT_INIT",
            "directories": [
                "<{GIT}>git"
            ]
        }
    ],
    "includeFiles": [
        {
            "if": "(LICENSE_TYPE != 'Unlicense') and (LICENSE_TYPE != 'None')",
            "files": [
                "LICENSE"
            ]
        },
        {
            "if": "LICENSE_TYPE == 'Unlicense'",
            "files": [
                "UNLICENSE"
            ]
        }
    ]
}

Template Language

Substitutions

Simple Value

Input:

This is a <{ thing }>

Parameters:

"thing": "test"

Output:

This is a test

Simple Value with Transformer

Input:

This is an uppercase <{ #uppercased thing }>

Parameters:

"thing": "Test"

Output:

This is an uppercase test

Built-in Transformers

• #lowercased
• #uppercased
• #uppercasingFirstLetter
• #lowercasingFirstLetter
• #trimmed
• #removingWhitespace
• #collapsingWhitespace

Conditionals

if ... ... end

Input:

<{ if isMonday }>
This is only kept if isMonday is true.
<{ #uppercased whatever }>
Some more text.
<{ end }>

Parameters:

"whatever": "Test",
"isMonday": true

Output:

This is only kept if isMonday is true.
TEST
Some more text.

if ... ... else ... end

Input:

<{ if thing }>
Thing is true.
<{ else }>
Thing is false.
<{ end }>

Parameters:

"thing": true

Output:

Thing is true.

Conditional Expression

The conditional expression can be more complicated than a simple boolean value. Here is the complete grammar for the conditional expression:

expr      := term ('or' term)*
term      := factor ('and' factor)*
factor    := 'not'? ( statement | '(' expr ')' )
statement := terminal ( ('==' | '!=') string )?
string    := ('"' | ''') character* ('"' | ''')

Example: if not ...

Input:

<{ if not isMonday }>
Today is not Monday.
<{ end }>

Parameters:

"isMonday": false

Output:

Today is not Monday.

Example: if not (... and ...)

Input:

<{ if not (isMonday and isRaining) }>
Today is not Monday and it is not raining.
<{ else }>
Today is either Monday or it is raining.
<{ end }>

Parameters:

"isMonday": true,
"isRaining": true

Output:

Today is either Monday or it is raining.

Example: if ... == "..."

Input:

<{ if license == "MIT" }>
This is the MIT license.
<{ end }>

Parameters:

"license": "MIT"

Output:

This is the MIT license.

Loops

for ... in ...

Input:

Here are some types of fruits:
<{ for fruit in fruits }>
Fruit name: <{ fruit }>
<{ end }>

Parameters:

"fruits": [
    "banana",
    "orange",
    "pineapple",
    "pear"   
]

Output:

Here are some types of fruits:
Fruit name: banana
Fruit name: orange
Fruit name: pineapple
Fruit name: pear

Longer Example

Input:

This is a test.
<{ #lowercased whatever }>
So is this.
<{ stuff }>
Whatever
<{ if potato }>
    Only if potato is true.
    <{ if cucumber }>
        Only if both potato and cucumber are true.
    <{ end }>
<{ end }>
Here are some types of fruits:
<{ for fruit in fruits }>
Fruit name: <{ fruit }>
<{ end }>

Here they are again:
<{ for fruit in fruits }>Fruit name: <{ car }> <{ end }>

Parameters:

"whatever": "[WHATEVER]",
"stuff": 1337,
"potato": true,
"cucumber": 1,
"fruits": [
    "banana",
    "orange",
    "pineapple",
    "pear"
]