Skip to content

Desktop Development and Version Control

There are many different desktop development tools available for code editing and version control.

We cannot document all possible tools but have attempted to outline the basic procedure for working on a developers desktop with P6 Sync and Platform6 configuration.

The procedure on MacOS is described here but the procedure on Windows or Linux desktops will be very similar.

1. Platform6 App development Folder

Create a root folder to contain all your Platform6 apps that you develop:

mkdir /Users/simont/Documents/myp6app

2. Obtain a ‘new’ app fileset

My local Platform6 instance is called simont-test and is configured to develop an application with the appKey of blok (this key was allocated when I registered my p6 app via the Management Console)

By issuing the following command I will build a local fileset from all service configuration I have created so far using my local instance:

p6sync -p6noproxy -app blok -approot /Users/simont/Documents/myp6app -pull new -instance simont-test

The fileset is simply a nested directory structure that describes the service configuration of my local development instance.

Note

This procedure shows how to work with a locally running Platform6 instance. By dropping the -p6noproxy option you can work with a remotely installed instance as easily as a local one.

** Warning **
'pull new' will destroy all existing folders and replace them with the current content of each selected p6 instance.
Are you sure? [y/n]: y
INFO: 2019/04/05 15:43:44 p6sync.go:661: 

Version: 1.0.0-SNAPSHOT, Build: 2019-04-05_01:37:39PM (79fbada), Platform: darwin:amd64, Using: go1.11.5 (dev) on 4 CPUs. TimeZone: BST (3600)

INFO: 2019/04/05 15:43:44 p6sync.go:473: No http proxy enabled.
INFO: 2019/04/05 15:43:47 p6sync.go:581: Identified sync instance(s): 1
INFO: 2019/04/05 15:43:47 syncmonitor.go:87: Pull sync initiated with instance: simont-test please wait...
INFO: 2019/04/05 15:43:51 syncmonitor.go:114: Pull sync complete. No errors detected.

Using the tree command you can see the fileset created. For simplicity it only shows configuration from the scripts service:

$ tree platform6.scripts/
platform6.scripts/
├── BlockHelloWorld
│   ├── meta.json
│   └── src
│       └── main
│           └── groovy
│               └── io
│                   └── platform6
│                       └── app
│                           └── blok
│                               └── scripts
│                                   └── blockhelloworld
│                                       ├── Main.groovy
│                                       └── MyLibClass.groovy
└── MyLib
    ├── meta.json
    └── src
        └── main
            └── groovy
                └── io
                    └── platform6
                        └── app
                            └── blok
                                └── scripts
                                    └── mylib
                                        ├── Main.groovy
                                        └── MyLocalClass.groovy

20 directories, 6 files

I have two scripts defined: BlockHelloWorld and MyLib. Code in MyLib is used by the BlockHelloWorld script.

See later for an explanation of the package structure used for scripts.

3. Configure Git

Move to your app root folder that P6 Sync created for you and initialise git:

$ cd /Users/simont/Documents/myp6app
$ git init
Initialized empty Git repository in /Users/simont/Documents/myp6app/.git/
$ git add .
$ git commit -m "Initial commit"
[master (root-commit) c6e9380] Initial commit
 7 files changed, 59 insertions(+)
 create mode 100644 platform6.scripts/BlockHelloWorld/meta.json
 create mode 100644 platform6.scripts/BlockHelloWorld/src/main/groovy/io/platform6/scripts/blok/blockhelloworld/Main.groovy
 create mode 100644 platform6.scripts/BlockHelloWorld/src/main/groovy/io/platform6/scripts/blok/blockhelloworld/MyClass.groovy
 create mode 100644 platform6.scripts/MyLib/lib.xslt
 create mode 100644 platform6.scripts/MyLib/meta.json
 create mode 100644 platform6.scripts/MyLib/src/main/groovy/io/platform6/scripts/blok/mylib/Main.groovy
 create mode 100644 platform6.scripts/MyLib/src/main/groovy/io/platform6/scripts/blok/mylib/MyOtherClass.groovy

4. Update Platform 6 Instance

You can make changes to the files in the app fileset and/or add new files, following the structure required by the owning service, and then update your instance with these changes. This can be done as a single stage (update) process, or a two stage (validate&update) process.

Here is an example of a single stage update to push changes made to the local fileset to your instance:

$p6sync -p6noproxy -app blok -approot /Users/simont/Documents/myp6app -push update -instance simont-test
INFO: 2019/04/05 16:06:16 p6sync.go:661: 

Version: 1.0.0-SNAPSHOT, Build: 2019-04-05_01:37:39PM (79fbada), Platform: darwin:amd64, Using: go1.11.5 (dev) on 4 CPUs. TimeZone: BST (3600)

INFO: 2019/04/05 16:06:16 p6sync.go:473: No http proxy enabled.
INFO: 2019/04/05 16:06:20 p6sync.go:581: Identified sync instance(s): 1
INFO: 2019/04/05 16:06:20 syncmonitor.go:282: Push sync initiated with instance: simont-test please wait...
INFO: 2019/04/05 16:06:21 syncmonitor.go:293: Push sync complete. No errors detected. 4 Item(s) processed. 1 Item(s) updated

Note

If changes have been made to your instance via the user interface tools you can keep your local fileset up-to-date using the -pull update option. Be careful as un-pushed local changes may be overwritten.

5. Git commit & push

Finally once you are ‘in sync’ with your instance, you can commit the fileset to version control:

$ cd /Users/simont/Documents/myp6app
$ git add .
$ git commit -m "My first changes"
[master 71a40d6] My first changes
 1 file changed, 3 insertions(+), 1 deletion(-)
$ git push

Create an IDE Project with your app fileset (IntelliJ)

You can configure your P6 Sync fileset as an IntelliJ project by performing the following actions:

  • New -> Project from existing sources
  • Select the app folder (e.g., ‘myp6app’) and select “import model as external project” as Gradle
  • Mark each src/main/groovy folder as Sources Root
  • You may also need to enable Git VCS for this project using the main menu

Once you have completed the above your project tree should look like ths:

IntelliJ Project

Validation & Update Task Configuration

The next thing to do is to define one or more ‘External Tool’ definitions to enable easy P6 Sync execution using IntelliJ menu options:

IntelliJ External Tool

Create an IDE Project with your app fileset (Visual Studio Code)

You can configure your P6 Sync fileset as a Visual Studio Code project by performing the following actions:

  • Open…
  • Select the app folder (e.g., ‘myp6app’)

Once you have completed the above, your project tree should look like ths:

Visual Studio Code Project

Git integration will be auto detected and is immediately available via the user interface.

Validation & Update Task Configuration

The next thing to do is to define one or more ‘Tasks’ to enable easy P6 Sync execution using Visual Studio tasks menu:

Visual Studio Code Tasks

Note

It is easy to mark a single task as the ‘Default Build Task’ making running it simple via the keyboard shortcut: Shift CMD B.

Script Service - Strict Groovy Package Structure

To ensure separation between scripts in different apps, we have adopted a strict package structure for all scripts compiled and executed by Platform 6.

Note

You never need to add package declarations to any script on Platform 6. In fact, as default if you do, it will be ignored!

Format is as follows:

io.platform6.app.['core'|app key].['scripts'|'routes'].[script name]

For example if you create a simple script called HelloWorld, the full classname of the compiled script will be:

io.platform6.app.blok.scripts.helloworld.Main

If you add a Groovy resource to the HelloWorld script called MyClass, it will be compiled as:

io.platform6.app.blok.scripts.helloworld.MyClass

If you use script libraries in your app, or an app provided script library via @include. For example if I create a Groovy resource called MyOtherClass in a script library called MyLib then the resulting name will be:

io.platform6.app.blok.scripts.mylib.MyOtherClass

Note

There is no need to add import statements for this auto created package structure, this is all taken care of by the Platform 6 runtime.

For more experienced developers wanting to get more out of their IDE and have some knowledge of Gradle there is an additional tutorial to follow here:

Tutorial