-
Notifications
You must be signed in to change notification settings - Fork 11
Developing the Authoring Tool
Information for people interested in developing the Ensemble Authoring Tool, the desktop app used for prototyping and developing new Ensemble domains.
The Ensemble Authoring Tool source is JavaScript that is packaged with Node.js and Google’s Chromium browser engine via Electron to form native desktop apps that can, for example, read and edit files on a user's filesystem—this is the main reason the Ensemble Tool isn't just a web app. We use Grunt, a JavaScript task runner, to automate the build process.
Browse the open tool issues to find something to work on here.
The relevant source files are in the ensembletool/ subdirectory.
Note these instructions haven't been tested with Windows or Linux development environments. They likely won't work perfectly if you aren't developing on macOS.
After making changes to ensembletool/ code, you can test some functionality by running an HTTP server and navigating to localhost:YOURPORT/ensembletool/ in your browser.
For example, if you ran the following command to start a server at the root of the repository:
python -m SimpleHTTPServer 8080
...then you could navigate to localhost:8080/ensembletool/ to interact with the tool.
You won't be able to load any new data files, because of file I/O security measures in browsers. You'll have to build the standalone desktop application to test with file I/O enabled.
The test console does load a default domain though. The files used are specified in the ensembletool/defaultdata/ directory. If you wanted to test with a different default domain, you could edit these files to replace their contents with your own test data. If you do this, be sure to keep the same filenames, as these specific filenames are currently hardcoded in ensembletool/js/ensembleconsole.js, and any other files in the defaultdata/ directory will be ignored.
As mentioned above, we use Grunt and Electron to build the tool. You should be able to build for macOS, Windows, and Linux systems all at once using the same pipeline, although Linux support is currently considered experimental—see issue #81.
If you're interested in modifying the build process, read the Grunt Getting Started page, the electron-packager docs, and the Ensemble Tool's Gruntfile.js. Be sure to update this document if any instructions change.
Building the Ensemble Authoring Tool requires Node.js, NPM, Grunt, and Wine (to make a Windows executable from a Mac). You also need the Java Development Kit (JDK) to generate documentation via jsdoc, but that isn't strictly necessary.
Note, NPM is installed when you install Node.js. Test if you already have them with: node -v and npm -v on a command line.
If not, download and use the installer programs (or package manager alternatives) on the Node.js website.
You may also want to ensure your NPM is up-to-date with npm update -g npm (some systems may require sudo).
See also: the Grunt Getting Started page
If you're using Grunt for the first time on this machine, open a command shell and install the Grunt command line interface (CLI) by running:
npm install -g grunt-cli
You might have to preface this with sudo (on OSX, *nix, BSD, etc) or run your command shell as Administrator (for Windows).
This will install the Grunt CLI globally, putting the grunt command in your system path, allowing it to be run from any directory, as long as you also have a local grunt install in that directory.
Now, if you aren't already there, move to the top level ensemble directory (where the js, jslib etc. folders live), and install Grunt locally by running:
npm install grunt
This should create a node_modules folder in this directory. You'll need to do this for every new directory that uses Grunt (e.g., if you re-clone Ensemble).
Then, install the project dependencies listed in package.json with:
npm install
See a list of your newly installed packages with npm list --depth=0.
Uninstall any version of Wine you've already got installed
brew cask uninstall wine-stable
brew uninstall wine
Ensure you don't have any version of /usr/local/bin/wine or /usr/local/bin/wine64 installed
Wine requires XQuartz. Install it:
brew cask install xquartz
Install a version of Wine that supports x64
brew install homebrew/cask/wine-stable
Clean out any lingering Wine config files you might have in your homedir
rm -r ~/.wine
(When you run the build process, it's ok to say "cancel" to all the Wine prompts about installing Mono, Gecko, etc.)
And finally, run the following to build the authoring tool!
grunt build
This will generate a directory called build/ with executable 32 and 64-bit macOS ("darwin"), Windows*, and Linux app files.
You'll be able run grunt build from now on in this directory, without having to repeat any of the above steps.
*The Windows app will not be generated if you're on a Mac and don't have Wine installed.