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
├── BlockHelloWorld
│ ├── meta.json
│ └── src
│ └── main
│ └── groovy
│ └── io
│ └── platform6
│ └── scripts
│ └── blok
│ └── blockhelloworld
│ ├── Main.groovy
│ └── MyClass.groovy
└── MyLib
├── lib.xslt
├── meta.json
└── src
└── main
└── groovy
└── io
└── platform6
└── scripts
└── blok
└── mylib
├── Main.groovy
└── MyOtherClass.groovy
19 directories, 7 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:
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:
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:
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:
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, if you do, it will be ignored!
Format is as follows:
io.platform6.[scripts|routes].[appKey].[script/route name]
For example if you create a simple script called HelloWorld, the full classname of the compiled script will be:
io.platform6.scripts.blok.helloworld.Main
If you add a Groovy resource to the HelloWorld script called MyClass, it will be compiled as:
io.platform6.scripts.blok.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.scripts.blok.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.