Summary: How to use the Script Compiler
The Monkey Script Compiler is a stand-alone executable which does not rely in any way on the Monkey Script Editor plug-in. You do need to have Rhino 4 installed on your machine for the Compiler to work. The Compiler is a little application which enables you to convert RhinoScript files (.rvb extension) into Rhino plug-ins (.rhp extension). The benefits of this are:
The disadvantages of compiling your scripts into plug-ins are:
The Compiler follows the standard Windows Wizard UI. You can start it from within Rhino (using the Monkey menu) or you can launch the Compiler by double-clicking on the application. Also, if you have an .mcp file (Monkey Compiler Project) on your system, you can double-click that file, and the compiler will start and load the project automatically. Or, you can drag and drop a number of .rvb files from Windows Explorer onto the Compiler icon and it will create a new project for those script files.
Note that the *.mcp format does not store the contents of the referenced script files, merely their location on the disk. If you rename/delete/move script files that are linked to a project, they will fail to load.
Plug-ins for Rhino are written either in C++ or a DotNET compliant language such as VB.NET or C#. Instead of the RhinoScript methods, plug-ins use the much more powerful Rhino SDK and since plug-in code is compiled into binaries, they run a lot faster than scripts. This is not the case for Monkey Compiled plug-ins. Although the actual plug-in is a precompiled binary which talks to Rhino via the SDK, your scripts are merely encapsulated and they will be extracted at runtime and run as though they are normal scripts. You will not see any difference in execution speed.
The Monkey Script Compiler is an easy to use piece of software that doesn't require an understanding of C++, DotNET or the Rhino SDK. Since chances are good that you are a programmer though (you may not be compiling your own scripts of course, it's just statictically more likely that you are), I will use programming jargon to explain how the Compiler works. Most of the following doesn't need more than a basic understanding of logic and software though.
The Monkey Script Compiler is a Wizard like application that guides you through the three required steps (and two optional ones) needed to make a compiler project. If you start the application, you will see the welcome page of the Script Compiler:
The Script Compiler provides some basic information about how to use the app. If you click the Next button, you will start with a blank plug-in project. This is what we're going to do, but if you already have a plug-in project file (*.mcp) you can load it by dragging it into the Load icon in the lower left corner of the welcome page.
Since this is the first time we're using the compiler, we do not have an existing *.mcp file and we need to start with a blank project. So press the Next button, which takes us to the Plugin Attributes page. If you open the plug-in manager in Rhino, you can access the properties of all loaded plug-ins (use the menu of the plug-in listbox). These properties include:
Some of these can be set to custom values:
In this picture, I have already filled out all the fields. There are two things you need to know here. First, the plug-in name must be a valid VB variable name. Thus, you are not allowed to use any weird characters, you are not allowed to use spaces (but you can use underscores), and you cannot start the name with a number. If you enter an invalid name the field turns red and the Next button is disabled. Note that when the Next button is disabled, there is something wrong with your settings. When this happens there will be a link to the left of the Next button which lists all problems.
The organization and web site attributes are important if you plan to enable license protection. See the licensing section for further details.
Once we have specified a valid name for our plug-in, the Next button on the Attributes page is enabled and we can move on to the Commands page:
Since we started a blank project, there are no referenced script files yet. We can add script references either by dragging them from Explorer into the list, or by using the Add Script button. Since we are still adding scripts, the Next button is disabled. You need to reference at least one script before you can move on.
If you drag files, they are given default attributes. If you use the Add Script button the command attribute dialog will be shown immediately. The image above shows that I dragged six files into the command list:
All these files have been given default attributes. They all have the same icon:
By default a referenced script will become a command named the same as the file. However, I want something more specific. I have two library scripts, which contain code used by the other scripts, and they should not be exposed as commands. Also, FourthScript.rvb contains some secret functionality and I don't want the command to be generally known. I need to change the script attributes to achieve this (double-click the script in the list, which will display the script attribute dialog):
Here you see the properties of the FirstLibrary.rvb script, after I checked the Library option (it is off by default). Library scripts are no longer treated as commands and all the other options are therefore disabled. Library scripts are loaded into the script engine before any command calls in their plug-in. It is important that you do not put any executing code into library files.
We also have to tag SecondLibrary.rvb as a library component, and we have to set the flag Hide command for the FourthScript.rvb. If you hide a command, it will not autocomplete in the command line and it will not be visible in the Plugin Properties dialog in the Rhino Plugin Manager.
After we have set all specific flags, the Command page looks as follows:
You can see that the library and hidden scripts have gotten a different icon and we are ready to move on to Step 3. Do note that command named (like the plug-in name) must adhere to Visual Basic variable naming conventions.
The last required step (which is valid by default) is to specify certain compilation settings. The Monkey Script Compiler has quite a few compilation settings, some of which are rather advanced and have a section of their own. The Compile page looks like this:
The compilation settings have been grouped under three categories: “Destination”, “Compiler options” and “Load options”. The Destination is simple, here you specify where the plug-in *.rhp file is to end up. The folder has to exist, or you will not be allowed to compile. By default, plug-ins will be put on the desktop. Upon compilation you are free to move the plug-in file wherever you like, it will run from any location.
There are two Compiler options available; encryption and license protection . The Script Compiler will encapsulate the referenced script files, but it is still possible for a hacker to reverse-engineer the original scripts. This is not easy to do, but if you are worried about this, you can enable encryption, which will encrypt the scripts with a 'private-key stream-cipher algorithm' making it much harder (but not impossible) to extract original script text. Encryption comes with a cost though, the scripts have to be decrypted before they can be run which results in a delay which becomes noticeable on large scripts.
See the licensing section on more information on plug-in licensing.
It is possible to save the project from the Compile page. Click on the Project icon button to save your *.mcp file to the disk. Note that this file contains all data required for a project (apart from the script contents, which are freshly loaded every time) including sensitive licensing info. Do not give this file to anyone if you have licensing enabled.
The Load options determine how your plug-in behaves when it loads. You can create a plug-in menu which will be added to Rhino when the plug-in loads. You can also specify whether your plug-in loads at Rhino startup or when it is needed (i.e. the first time when a command in your plug-in is called). Generally, plug-ins are loaded when needed, but if you have defined a menu, you may want to load the plug-in right away or else the menu will not be visible. Also, you can specify a message to print when the plug-in loads. The following screenshot shows custom compilation settings for our example project:
We are now ready to compile the plug-in. In theory, since the Compile button is enabled we should encounter no problems. However, this is beta software and it is possible we have missed some rare case which causes problems. If everything goes well, you will see the following, final page of the Wizard:
If the compilation failed, the central textfield will contain the compiler report, with all errors and warnings that were encountered. If you experience a failed compile, please send the content of this texfield to the developer
The Script Compiler comes with a menu editor which allows you to create a fully customized menu. This menu is inserted at the end of the Rhino main menu (but before the Help menu) when the plug-in is loaded. By default, a plug-in does not define a menu so you have to specifically enable this on the Compile options page. If you check the Create plugin menu option, the Menu editor… button is unlocked. There is a default menu setup, which will be created when you first enable the plug-in menu. It consists of a root item which has a similar name as the plug-in, and a simple list of all non-hidden commands in the plug-in:
Let's say that we want some more commands in there that are useful macros for people who are using our scripts. We want to make them slightly less important that the actual commands, so we'll separate the two groups and even nest some of them. First however, we add the items using the buttons on the toolbar. Menu items come in three flavors; active items, parent items, and separators. Parents and separators do not have macros assoiated with them, and separators have no names either. Only active items do something. You can specify both the name and the macro of an item. When you select an item in the tree, its properties are loaded. You can also change the name of an item directly in the tree:
When you add an item (be it a menu item or a separator) it will append to the currently selected item. Since the root item is selected by default, we end up with a straight list of new items. You can reorder items by dragging them around. Since you need to be able to both reposition and nest items, the dragging in the editor works slightly different from what you're used to:
Feedback is drawn in the tree so you always know what happens when you drop an item in a particular spot. The image below shows a drag operation which will result in a nesting:
When you are done reordering our menu structure, you can click OK to return to the Compile page. When you compile this plug-in, the menu in Rhino looks like this: