Tutorial: Add a New Project Type

Tutorial: Add a New Project Type

This tutorial will show you how you can add a custom project type via an addon. The assumption here is that the programming language to use is already supported by Project Init and you want to add a new project type to the system. For the purpose of this tutorial we will show how to add a new Java project type. So effectively, what we achieve is that in the end we have an addon which adds another item of available Java project types to this list. Of course, the same principles apply to project types of other languages. 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 of 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.

Create a New Project Type

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 create a new project type for the Java programming language.

Create the Directory Layout

All project type resources must be located under the java subdirectory. Create that subdirectory inside our addon:

mkdir java

Then, for each project type we have to create a separate subdirectory inside the java subdirectory. Our new project type will be for initializing an example app, so we'll call the project type My Example Application. Inside the list of available Java-based project types, we want our example app to be at position 4. So we embed that information into the directory name as this will determine the order of the list items. So let's create the subdirectory for the new project type:

mkdir java/04A_example_app

Create the Name File

First, let's tell the Project Init system the name of our new project type as it should be displayed to the user. Otherwise the name of the directory is used, which is not that pretty. Create a file name.txt and insert one text line representing the name of the project type:

echo "My Example Application" > java/04A_example_app/name.txt

Create the Init Script

Since the new project type 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 new project type from the list.
Create the init script for the project type:

touch java/04A_example_app/init.sh

Now, depending on what you want to do with a paricular project type and how much you want to automate the project initialization, an init script can be arbitrarily complex. For this tutorial, however, we'll keep things simple and create a very small init script. Let's say that we want to ask the user to enter the target version of the JDK to use when initializing from our project type. Luckily, there is already an API function that does what we want. So inside our init script we only have to call the form_java_version() function and the user will be prompted to answer the corresponding form question. Later on, we could get the Java version chosen by the user inside a source template file by using the ${{VAR_JAVA_VERSION}} substitution variable.

We then only have to call the three obligatory initialization functions to instruct Project Init to create a new concrete project from our source template. In summary, add the following code to the init script of the new project type:

# File: java/04A_example_app/init.sh

# Form questions

form_java_version;

# Project setup

project_init_copy;

project_init_license "java";

project_init_process;

Create the Source Template Directory and Files

Finally, 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 project type. These files represent the blueprint so to say of our introduced Java example app. All source template files should be located inside a source subdirectory of our project type directory. Create it with:

mkdir java/04A_example_app/source

You can put whatever files you want inside that subdirectory. As a very minimalist example, you could 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 Java example app. For example, you could add the following content to the java/04A_example_app/source/README.md file:

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

My example application.


## License

${{VAR_LICENSE_README_NOTE}}

As our example app is a Java application, we would need a class with a main() function.
So you could add the following content to the java/04A_example_app/source/Main.java file:

${{VAR_COPYRIGHT_HEADER}}


public class Main {

    public static void main(String[] args){
        System.out.println("This is an example addon");
        System.out.println("${{VAR_PROJECT_SLOGAN_STRING}}");
        System.out.println("Using ${{VAR_JAVA_VERSION_LABEL}}");
    }
}

Anyway, you probably get the point. Use the provided API functions together with substitution variables to parameterize the project initialization, and with that, make your own life or the life of other people easier.

Using the Addon Project Type

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

project-init

You should see the example app in the list of available Java project types:

Congratulations! You just created a custom project type for your Project Init addon.