Script Only Stacks

In LiveCode 8 there is a new option in the (new) ‘New Stack’ submenu:

This new option allows you to create what is called a ‘script only stack’.

Now, ‘script only’ stacks have been around for a quite a few versions now – they were added by me a couple of years ago after much frustration battling with merging updates across three branches for the IDE’s iOS deployment code.

At that time, the library which actually does iOS standalone building was a conventional library stack, it was a binary stackfile with just a stack script. Binary stackfiles are very convenient, but they do cause problems for version control systems such as git. Git is great at dealing with text based files, but will not deal in any way with binary files (beyond allowing you to store and fetch them).

At the time, we were having to patch the iOS standalone builder a lot, and having to do so across 3 separate branches. Not only was this tedious but also highly error prone. So, one day when battling with this particular task I decided to try and do something about it…

The key library stack which was in question was ‘revsaveasiosstandalone.livecode’ which sat (at the time) in the LiveCode IDE open-source repository. Now this stack was a pure library stack – it has no controls, no custom properties, and the only non-default properties were the stack’s script and the stack’s name. Indeed, the values of these properties was the only ‘interesting’ information in the stackfile itself. This observation led to the ‘script only stack’ feature.

In a nutshell, a script only stack is a text file, structured in a specific way, which the engine can load and save as if it were a normal stackfile. When the engine loads a script only stack, it creates a stack with the name specified in text file and sets the stacks script property to the script specified in the text file. When the engine saves a script only stack it reverses this process, writing out a text file containing the stack name and stack script and absolutely nothing else.

The beauty of script only stacks is that they work incredibly well in version control systems like git. Indeed, a script-only stack is nothing more than a source-file in the same vein as you would see if writing code for C++ or a similar lower-level language.

One can see the difference by getting text edit to display the content of a script-only stackfile and a normal binary stackfile:

On the left you see the content of the stackfile when ‘ExampleLibrary’ is saved as a script only stack; on the right you see the content of the stackfile when ‘ExampleLibrary’ is saved as a normal stack.

The key thing is that the left hand file is a true bonafide text file. It has no sequences of binary data in it which cause git to throw up its hands, and very clearly shows the two bits of information which represent any script only stack: the stack name, and the stack script.

The fact that script only stack files really are just text files is really important! It means you can edit and create them in any text editor you choose, and use any text based processing tool on them (the key thing for git is that you can diff and patch them)! The only thing to remember is that the very first line in the text file has to be of the form:

script "<name>"

With every line after the first being taken as the stack script.

After the initial implementation of the script only stack feature it gained more and more use in the IDE as we converted most of the IDE libraries into script only stacks (things such as revLibURL, revCommon, revBackScript, …). In almost all cases this was trivial, the most we found was that some of the libraries stored constants in custom properties which were easily moved to be in the script. This process meant that more and more of the IDE’s components which did not have a UI part were now much easier to modify. Furthermore the process of reviewing and merging patches to those components as part of our GitHub-based engineering workflow became a great deal less time intensive!

Some time later we made one more tweak to the engine to increase the scope of script-only stacks even further: we made it so that any behavior reference could not only be a button, but also a stack. This final piece of the puzzle meant that even more of the IDE could be factored out into text files. Any component which relied heavily on behaviors could now be split up into a small (binary only) UI part, and a collection of (text only) script only stacks. This model has been the basis for a good part of the restructuring of the IDE which has occurred in the work for LiveCode 8.

So, that’s probably enough background, the question now is how do you use them?

Beyond the new option in the ‘New Stack’ menu in LiveCode 8 there are a couple of pieces of engine syntax which are useful to know about.

The first is the command which you can use to create a script only stack:

create script only stack theName

The second is the property you can use to not only find out if a stack would be saved in script only format, but also to change whether it will be or not:

the scriptOnly of stack theName

I, personally, find the best way to think about script only stacks is to consider the scriptOnly property as controlling the output format of the stackfile. If the scriptOnly property is true, then the stack will be written out as a textfile and anything other than the stack name and stack script will be discarded. If the property is false, then the stack will be written out as a normal stackfile and nothing will be discarded.

Shortly after the initial implementation there was various amounts of discussion about certain aspects of the feature. In particular should the engine control what you can do to a script only stack at runtime? (i.e. only let you change the name and script, and not create any controls or add any other properties), and can we extend the script only format to include more than just the stack script? In both these cases we decided that neither would be appropriate. All things being equal, simplicity is always the best option. Keeping the feature simple and slim means that it is incredibly easy to use and incredibly easy to explain.

I have to say that I think script only stacks (although such a simple idea) have made one of the biggest improvements to our workflow for working on the IDE. Indeed, I’d go as far to say that they are perhaps a big part of why we have been able to accelerate IDE development so much over the last couple of years whilst we have been working on LiveCode 8.

So, if you have projects with lots of library stacks, or lots of behaviors and want to start using version control to help your development process then why not give script only stacks a try – you won’t ever look back!