Article
· May 22, 2017 3m read
Open Exchange

Port: A VCS-agnostic and project based Studio source control tool - Basic Usage

#Change Management #Git #Mercurial #ObjectScript #Caché

EDIT: This article has been updated with up-to-date information about the Port project, which now includes a tutorial for basic usage.

The Port project is something that I've introduced more than two years ago but I hadn't enough room to elaborate a tutorial on how to use it till now.


First, the motivation:

 

I started this project several months  years ago when I noticed that most of the Studio's source control implementations weren't project based but instead namespace based. While developing it I noticed some potential keys factors that made me put a bit more of effort on it, even though there were options to handle the source codes already. These factores are:
 

  • Organization: A Project to be used as a finite scope, thus never mixing code that don't belong there.
  • Tests: Projects allow restricting test suites to their scope, thus allowing easier execution.


There are another few points that I left out because they aren't directly related as to why use projects.

A word of warning though...

If you want to use Port with a shared instance then I'd recommend you to try something else. Port is not made for usage with shared instances as it strongly favors distributed development. It's ideal for personal projects but might not be suited for big enterprise enviroments.

If you fail to understand this, you'll face code duplication, desynchronization and even overwrites due to your fellow team mates modifying the same source code.

Now back to what matters...

I've been using Port to handle every Caché Studio-based project and I want to share the why, but this time in a pratical sense, so I made this tutorial to help you understand a bit more. Follow the steps below and if you find any problems you're free to open an issue or report it back in this thread, you can even PM me if you want and I'll reply when it seems fit.

1. Download and install the file port-prod.xml

After installing it, Port will ask you to restart the Studio.



2. Create a new project, create a new project item, save the project and the item respectively.

Everytime you create a new item you must save the project before the item, to make sure that the Studio already updated the project reference.
Port will handle creating the directory structure for you, whichs defaults to: /CacheProjects/{NAMESPACE}/{PROJECT}.


3. Save the recently added item.

This will make the item to be exported. Port will always assume that every project item is a candidate for being exported, this is also why you don't need to worry about Check-In'ing/Check-Out'ing these items.

 

4. Export a project as whole using the menu Source Control->Export.

The first thing that you'll want to do is to export the project as whole. Specially the already existing ones, when doing so Port will check which exported files are outdated and overwrite them with the ones in your project.

NOTE: Port will remove files that aren't related to the project in order to keep clean the directory where the source code is exported. This happens over two circunstances: when removing from the project  or deleting the item. So make sure you know what you're doing and commit often!



5. Import files modified externally by using the menu Source Control->Import

Let's suppose that you have git pull'ed recent changes from your remote and now you need to put these changes in your project, you can do so by importing it back.

If you just cloned a repository that you want to add to Studio then create an empty project using it and import the files using the same menu option.
Just make sure that the repository path respects the same path used by import (which defaults to /CacheProjects/{NAMESPACE}/{PROJECT} as explained before).



6. Force an item to be exported or imported by using the context menu: Source Control->Export (forced) or Source Control->Import (forced).

You can also force an item or even a whole project to be exported/imported. Forcing it means bypassing the timestamp checks, you might need it eventually.

NOTE: You can also import a folder or a Package, all items that belong to it will be affected as well.

 

This concludes the tutorial about the basic usage. Next time I'll be covering how to execute unit tests integrated to the project using the Studio.

Check the related application on InterSystems Open Exchange
Discussion (5)1
Log in or sign up to continue
Evgeny Shvarov · May 22, 2017

Hi, Rubens!

Thanks for sharing this!

I like to see UDL code in sources and folder=package structure for the source code.

Few ideas:

Why not save code without txt extention? Cls would go with .cls, include files with .inc and etc, like in this project, or  this project or in that one.

Would you please share a small screencast video of the general use cases which shows the key advantages and benefits?

Thank you in advance!

1 0
Rubens Silva · May 22, 2017

If you want a proof-of-concept or a showcase, then this link shows how the class package hierarchy is followed.

You can disable the use of .txt using two ways: 

1 - By running ##class(Port.SourceControl.Config).SetSourceExtension("")

2 - By running the wizard with ##class(Port.SourceControl.Wizard).Start() and navigating to the relevant option.

Note that this will ONLY AFFECT the appended extension, not the type itself. Example:

##class(Port.SourceControl.Config).SetSourceExtension("")  = cls/Port/SourceControl/Hooks.cls

##class(port.SourceControl.Config).SetSourceExtension("txt")  = cls/Port/SourceControl/Hooks.cls.txt

All the same for following formats: INC, INT, MAC, DFI, MVB, MVI, BAS. Except if the file is inside the web (CSP) path.

I could do a small screencast, but the usage is pretty straightforward. Anything more advanced than that is covered by the Wizard.

How to use:

1 - First time only:  import the port.xml.

2 - Run ##class(Port.SourceControl.Installer).Install().

3 - Restart the Studio.

4 - Done! Now whenever you save a file related to the project, it's structure is generated and the file is exported everytime you save it.

5 - If you want to export all items regarding the current project you can use Source Control->Export Current Project.

EDIT: Oh I forgot mentioning about tests.

Unit testing with Port:

As long as you have classes prefixed with the package "UnitTest" (which is also configurable). You can export these classes to XML and run their tests atomically.

1 - SourceControl->Export Test Suites to XML.

2 - Context SourceControl menu->Run Tests Associated with this item.

 

By default when you install Port using the installer, it sets a parameter to run unit tests as you keep compiling the classes.
You can disable that as well.

If you notice any bugs, please fill a issue.
If you still need a demonstration, please ask again.

1 0
Rubens Silva · May 22, 2017

Just like a CSP file.

You have two ways of working with that:

 

1 - If you modify the file using the Studio, that file is exported automatically when you save it.

 

2 - If you modify the file outside the Studio you can import the file again to the project and it'll be overwritten with the new version (as long as it's newer).

Anything inside the web folder is mirrored inside the csp application. Which means:

If you have a file with the path 
C:\CacheProjects\yourproject\web\css\index.css 

It's name will be resolved to:
csp/namespace/index.css

And will be mirrored like this:
C:\InterSystems\Cache\CSP\namespace\css\index.css

If you remove that file from the project, save it and export, then this file will be eliminated from the repository since it doesn't belong to the project anymore.

The same rule is applied for each type. Not only the folder "web".

0 0