Tutorial: Add a New Programming Language

Tutorial: Add a New Programming Language

This tutorial will show you how you can add a custom programming language via an addon. At the end of this tutorial you will be able to select an additional programming language in the main Project Init form. We are not going to use a real programming language here, but you may use this tutorial as an example or starting point to integrate support for your language of choice. The principles described here apply to any programming language. The example code of this tutorial is also available in the addons directory of the Project Init repository.

Create an Addon Resource

First we need to create our addon. If you already have one, then you can skip this step. To keep things simple, we straightforwardly use a directory on the local filesystem as our addon resource. Later on, you can still put your addon in a Git repository to make it easier to manage. But for now, we'll keep it as a plain directory.

Create a new directory for your addon. For example, create a directory my-addon in you user's home directory and cd into it:

mkdir ~/my-addon && cd ~/my-addon

In order to mark the newly created directory as a Project Init addon, we must also create an empty file named INIT_ADDONS at the root of our addon resource directory:

touch INIT_ADDONS

Then, in order to tell Project Init to use our new addon, we must set the environment variable PROJECT_INIT_ADDONS_RES to the path to the addon's directory. Since we're already in it, we can use the PWD shell environment variable to give us the absolute path:

export PROJECT_INIT_ADDONS_RES="$PWD"

Please note that it is recommended to set the PROJECT_INIT_ADDONS_RES environment variable automatically, for example inside your user's .bashrc file (see the Setup section for more information). If you do so then make sure you use the correct absolute path and not the PWD shell variable.

Add a New Programming Language

We now have an addon resource ready to be used. There are various files we could add to configure how the Project Init tool behaves, see the Readme in the official repository for examples. But for now, let's only add support for a new programming language. Please note that we are not going to introduce a real programming language here, but rather just use an example for demonstration purposes. If you want to add support for, let's say TypeScript, then you should use the appropriate directory and file names instead.

Create the Directory Layout

Project types are separated by the underlying programming language/technology. Since we're introducing a language that is not already supported by the base system, we have to create a separate directory for it. All project type resources for our example programming language must be located under the example subdirectory. Create that subdirectory inside our addon:

mkdir example

Create the Name File

We have to tell the Project Init system the name of our new programming language as it should be displayed to the user. Otherwise the name of the directory is used. Create a file name.txt and insert one text line representing the name of the programming language:

echo "Addons Example" > example/name.txt

Create the Init Script

Since the new programming language of our addon is located on its own init level, we have to provide an init script for it. This tells the Project Init system what it should do when a user selects the language from the list.
Create the init script:

touch example/init.sh

Depending on how much you want to automate the initialization process for new projects in the custom language, an init script can be arbitrarily complex. For this tutorial, however, we'll keep things simple and create a very small init script. In fact, we only add the bare minimum code to our init script to make our example work.
Add the following code to the init script:

# File: example/init.sh

select_project_type "example" "Example";

proceed_next_level "$FORM_PROJECT_TYPE_DIR";

As you can see, we only have to call two functions at this init level. First, the select_project_type() function lets the user select a project type under the example subdirectory. We don't have a project type yet but will create one below. The directory of the project type chosen by the user is saved in the FORM_PROJECT_TYPE_DIR global variable. We then pass that information to the proceed_next_level() function to instruct Project Init to descend into the next init level, i.e. the directory containing the selected project type.

Create a Project Type

All project type resources for our custom language must be located under the example subdirectory. For this tutorial we only provide one concrete project type. We therefore need to create another subdirectory for it.
Create that subdirectory inside our addon:

mkdir example/01_example

Please note that since we only have one project type, it will be automatically selected as soon as the user chooses our custom example programming language.

We then have to create the files for the project type. First, let's create the name file:

echo "Executable Script (Addons example)" > example/01_example/name.txt

Then create the init script for the project type:

touch example/01_example/init.sh

Since we don't have any more init levels after that, that init script must call the three obligatory initialization functions to instruct Project Init to create a new concrete project from our source template. Because we don't have any other customisations or form questions to ask, those three functions are effectively the only functions we call in the init script. In summary, add the following code to the init script of the project type:

# File: example/01_example/init.sh

project_init_copy;

project_init_license "sh";

project_init_process;

Create the Source Template Directory and Files

Lastly, the only thing we need is our source template files. These are the files that are copied and processed when a new project is initialized based on our custom programming language and concrete project type. These files represent the blueprint so to say of our introduced concrete example project type. All source template files should be located inside a source subdirectory of the underlying project type directory. Create it with:

mkdir example/01_example/source

You can put whatever files you want inside that subdirectory. As a very minimalist example, let's just create a short README.md with some preexisting structure to make it easier for people to get started after they have initialized a new project based on this example project type. You could add the following content to the example/01_example/source/README.md file:

# ${{VAR_PROJECT_NAME}}: ${{VAR_PROJECT_DESCRIPTION}}

My example application with a custom programming language.


## License

${{VAR_LICENSE_README_NOTE}}

Normally, you would then also add some source code files in a directory layout specific to the concrete programming language. Since our example programming language is fictional, let's just add a small shell script instead. Consider this to be a placeholder in case you want to build upon this tutorial with a real programming language and addon.
So you could add the following content to the example/01_example/source/myscript.sh file:

#!/bin/bash
${{VAR_COPYRIGHT_HEADER}}

echo "${{VAR_PROJECT_SLOGAN_STRING}}";

In a real addon you would of course do more interesting things than the code shown so far. Use the provided API functions together with substitution variables to parameterize the project initialization.

Using the Addon Programming Language

Now simply run Project Init to initialize a new project from the resource provided by the addon:

project-init

You should see the Addons Example in the list of available programming languages:

Congratulations! You just added a new programming language to Project Init via an addon.