Skip to content

Concepts

Jump to bottom
Trenton Young edited this page Aug 20, 2024 · 9 revisions

Tool

Tools (one of the things that make up a Path) are things like package managers, programs, and other things that are generally installed as-is for use during development (e.g. NodeJS, ImageMagick, GIMP). Tools are strictly installed before Modules, logically making all Modules dependent upon each Tool. Tools are defined with:

  • scripts (required)
    • check: Checks if the tool is already installed, skipping the installation step
    • install: Installs the tool if it is not already installed
    • uninstall: Used to undo any installations in the case of some kind of failure
    • Scripts may be defined for specific platforms (only Windows, MacOS, and Linux supported) or any platform.
  • mode (optional)
    • install (default): This default is implied when no mode is defined. The Tool will be installed as usual
    • optional: The CLI will prompt the user whether of not to install the Tool
    • as_alt: The Tool will be only be installed if another Tool that names it as an alt fails to install
  • depends_on (optional)
    • This allows Tools to be dependent on each other, as in the case where one Tool may be used to install another or one Tool extends another.
  • alt (optional)
    • If this Tool fails to install, the Tool defined in alt will be scheduled for installation

Failure to Install

If a Tool fails to install when a Starterfile spins up, all Tools that were successfully installed by the CLI will have their uninstall scripts run. A Tool for which its check script passes will NOT have its uninstall script run. This should prevent pre-existing Tools from being rolled back erroneously.

Module

Modules (one of the things that make up a Path) are usually frameworks or templates that are meant to be extended, worked in, or otherwise used as a starting point to be edited (e.g. a Flask API, a React App, a Mongo database). Modules may take one of two forms: a script, or a git repository. Modules are defined with:

  • dest (required): Uses environment variable replacement
  • source (required): Takes either git with a repository reference or [a script that may be multiline]
  • Scripts (required)
    • init: Called once the source is collected
    • destroy: Used for cleanup in case of some kind of failure
    • Scripts may be defined for specific platforms (only Windows, MacOS, and Linux supported) or any platform.
  • depends_on: (optional)
  • This allows Modules to be dependent on each other, as in the case where one Module relies on any number of others.
  • init_options (optional)
    • This optional feature is a contract between the Module and the user, allowing for settings to be chosen while the Path is being initialized. For example, a React Module might prompt the user to choose between TypeScript and JavaScript.
    • env_name: The name of the environment variable to save the value to
    • prompt: A string to use when prompting the user for input
    • default: The default value to use (promotes opinionated Paths)
    • type (optional): If defined, will override the type of the default from its interpreted type (e.g. default=0, type=float)

Git Module

Commonly, Modules will be defined as a template repository on GitHub. This approach is ideal for reusing Modules across several different Paths and allows Path designers to get a better idea of the Module before using it.

Git Modules are cloned to the working directory (INSIDE the local repo created by calling startout-paths) and then their init scripts are called once all Modules have been collected (in dependency order).

Script Module

Script Modules are used for very Path-specific needs, since they are not as easy to share or maintain. Potential uses for Script Modules are setting up file structure or downloading scripts (see security advisories).

Script Modules' source script is ran when they are "collected" (the step where a Git Module would be cloned), and then their init scripts are called once all Modules have been collected (in dependency order).

Path

Paths are composed of Modules and Tools. They are sometimes referred to as "hypertemplates," "platform templates," or similar language. A Path will nearly always exist as a GitHub repository, because it includes not only code but also CI/CD pipelines, environments, and project management tools.

Though it is best practices for the static repository to resemble the end result of opening a Path, the Path's repository may not exactly reflect the end result. This is because the Starterfile at its top-level has the big job of collecting and installing all of its Tool and Modules (in that order) when the Path is opened. Some file structure may be in place, though it is possible that there is some "pruning" (deleting directories/files that will be replaced by the Starterfile) that may happen.

Note

In order for the CLI to recognize a template repository as a Path, it should contain a Starterfile.yaml at the top-level and the custom property "Golden-Paths" set to "Path" (case sensitive).

Starterfile.yaml

The Starterfile is the driving force when opening a Path. This YAML file is parsed and executes all the steps to collect and install each Tool and Module defined by it. The Starterfile maintains dependency order of each Tool and Module, and makes sure that you're getting the latest version of each one when you open the Path.

Check out this page that details the structure and requirements of a Starterfile.

Startersteps.md

This file is generally a set of instructions that must be carried out manually due to challenges to automation. There is usually a workflow defined in the Path that checks if this file still exists whenever you push to your repo, this is just a reminder and can be deleted when the steps are complete.

Clone this wiki locally