-
Notifications
You must be signed in to change notification settings - Fork 18
Setting Up a Dev Environment
If you're planning to hack on Openframe, you'll want to set up a dev environment which makes it easy to update code and see the results right away. Openframe uses familiar tools like GitHub, Node, and NPM, and we'll use some standard development practices of these tools to get setup.
This guide is for people developing on the Raspberry Pi. Here we'll describe setting up an environment suitable for working on the Openframe frame controller and modifying or developing new extensions. This setup will still use the public Openframe server, so you can use your account at openframe.io to add and push artwork to your modified frame.
- Create an Openframe-ready SD Card following the Openframe User Guide. Enable SSH and, optionally, setup Samba.
- Fork the Openframe repo, and any extension repos you plan to work on / mess around with.
- On the Pi, clone each repo, and
npm installtheir dependencies. - In each of the extension repos, use
npm linkto create a global symbolic link for this npm package - In the Openframe repo, use
npm link [extension-a-package-name] [extension-b-package-name], passing each linked extension package name. - In the Openframe repo, run
npm start. Now Openframe is running from the source code, using the source code of the extensions. - Get to work. You can SSH into the Pi and edit files directly there, or use Samba to mount the files on your computer and work on them with your favorite editor.
In order to make sure the Pi has all of the necessary dependencies installed, the simplest thing to do is to set up an SD Card following the Openframe User Guide. Make sure you've got an Openframe account and that you can log in and push artwork to your frame. You probably don't want to enable 'autoboot to Openframe', since you'll be launching Openframe yourself.
It's helpful to enable SSH on the Pi so that you can edit files remotely. If you're comfortable setting up and using vim (or whatever editor) on the Pi and doing your development work there, that's fine. If you'd prefer to use your usual editor, you can use Samba to mount the Pi's file system on your computer and edit the files directly.
There's a good tutorial on setting up Samba on the openFrameworks site.
You'll want to fork the Openframe repo to your own GitHub account. This way you'll be able to keep track of your work and contribute bug fixes or enhancements 😄.
More info on forks and the GitHub collaborative workflow is available on the GitHub site.
Log into the Pi terminal, via SSH or directly, and git clone your repos. You'll clone your forked Openframe repo, and whatever extension repos you're working on. These might be forks of existing extensions, or a repo for a new extension.
Once you've got the source code for each project on the Pi, npm install in each repo directory to install all of the dependencies. Some extensions take quite a while to install!
As a quick test, you can run the Openframe from the source code and make sure it works. Just go to the Openframe project dir and type npm start. If you've already logged in when you initially installed openframe, the frame should start using the same credentials. It may ask if you want to autoboot, which you should decline.
Extensions are just Node packages, following standard NPM package practices. They are specified by their NPM package name, as defined in the package.json file. The package name must be all lowercase, and as a convention should follow the pattern 'openframe-[extension-name]'. For example, the Openframe-glslViewer extension has a package name of 'openframe-glslviewer'.
If you are indeed working on extensions, you need to make sure that the local version of Openframe you're running is pulling in the local versions of the extensions. As this is a common need when developing inter-dependent projects, NPM provides a handy way of managing this. You'll use NPM's link command to create a global symlink for the dependencies, then use it again to tell the dependent project to use the symlinked version.
In each of the extension project directories, run npm link. This will create the global symlink.
Then in the Openframe project directory, run npm link [extension-name] [another-extension-name], passing each package name (from package.json) for the extension repos you'll be working on.
That's it! Now the Openframe project will point to the linked extensions, so changes to the extension's files will take effect immediately within the Openframe project. Great!
Whenever you make changes to files, you'll need to restart Openframe on the Pi by running npm start in the Openframe project directory.
Openframe uses (and encourages you to use!) the debug package. You can see the debug output by specifying the DEBUG env var when starting Openframe. E.g. to see all debug output:
DEBUG=* npm start