Using Processing via the Command Line

For those of you who aren’t familiar, Processing is an open source programming language originally developed by Casey Reas and Benjamin Fry, and took its first steps over at MIT. It is a really great language built from java created for use by visual artists and designers. The language itself is geared towards non-programmers, so it is fairly easy to pick up the syntax. However, it still holds as a very powerful and flexible object-oriented programming language. Head over to OpenProcessing.org or Processing.org if you want to get a good idea of some of the amazing things that can be done with Processing.

I have been using Processing on and off for a few years now, and I think it’s pretty great. I really like how lightweight it is, and how rapidly you can develop interesting visuals from a small amount of code. However, I am really much more comfortable programming and working via the command line. I also would prefer to use vim to write Processing sketches instead of their built in IDE (muscle memory I guess?). I could always run scripts in processing and develop in vim, but that’s kind of a pain switching back and forth between applications.

Fortunately, since the 2.0b4 release, Processing has started supporting a command line tool called processing-java. Once I discovered this, I decided to give it a try, and after playing around with it for a little while, I’m glad I did. Sure, it’s not for everyone, but for those of you who desire unix command line functionality, its a pretty nice little utility.

If you are interested in working with Processing via the command line, the first thing you will need to do is download the command line program, (you’ll need Processing to do this, so if you don’t have it, head over to Processing.org and download the latest release) luckily, Processing made this really easy for us; all you need to do is open up the Processing app, then go to tools -> Install “processing-java”:

Once installed, you should be able to access this program via the terminal. You can test this out by using the following command in your favorite terminal application:

% processing-java --help

Command line edition for Processing 0221 (Java Mode)

--help               Show this help text. Congratulations.

--sketch=<name>      Specify the sketch folder (required)
--output=<name>      Specify the output folder (required and
                     cannot be the same as the sketch folder.)

--force              The sketch will not build if the output
                     folder already exists, because the contents
                     will be replaced. This option erases the
                     folder first. Use with extreme caution!

--build              Preprocess and compile a sketch into .class files.
--run                Preprocess, compile, and run a sketch.
--present            Preprocess, compile, and run a sketch full screen.

--export             Export an application.
--platform           Specify the platform (export to application only).
                     Should be one of 'windows', 'macosx', or 'linux'.
--bits               Must be specified if libraries are used that are
                     32- or 64-bit specific such as the OpenGL library.
                     Otherwise specify 0 or leave it out.

As you can see this is a fairly simple utility. However, it operates slightly differently than running scripts from within Processing. One of the big drawbacks, is that you have to have a saved sketch, within a sketch folder, and an output folder, before you can run this utility. I find myself going back to the Processing IDE to run small tests on sketches that I don’t feel like saving, or using their IDE to develop sketches that don’t contain a large code base.

As it stands, this utility is a little clunky to use. Here is an example of how to run a basic sketch from start to finish:

% mkdir test_sketch
% mkdir test_sketch/output_dir
% echo "size(500,500);" > test_sketch/test_sketch.pde
% processing-java --run --sketch=`pwd`/test_sketch --output=`pwd`/test_sketch/output

You will get some output like this once you run the program:

Listening for transport dt_socket at address: 8497
Finished.

If you want to rerun this sketch after editing it, you will have to delete the output folder, or run the processing-java command with the –force option (I didn’t have too much luck with this method), which doesn’t lend itself well to the rapid development that I am used to with the Processing IDE. However, using the power of the unix environment, we can actually take a lot of these repetitive steps out of the process by setting up some bash functions, making the processing-java program a little more user friendly. Here are the bash functions that I use while working with processing-java:

function prun {
     if [[ $1 != *'/..'* && $1 != *'../'* && $1 != '.'* && $1 != '/'* ]]
     then
          [[ $1 == "" ]] && sketch=`pwd`;
          [[ $1 != "" ]] && sketch=`pwd`"/"`echo $1 | sed 's;/$;;'`;

          processing-java --sketch="$sketch" --output="$sketch/.tmp_output" --run;
          rm -r "$sketch/.tmp_output";
     else
          echo 'ERROR: Please enter the path to your sketch relative to your current location, ".", "..", "~", and full paths will not work with this function';
          echo '       If you are in the sketch folder you want to run it, simply exicute prun with no arguments';
     fi
}

function psetup {
     sketch=$1;
     mkdir $sketch; touch $sketch/$sketch.pde; cd $sketch;
}

To play nice with the processing-java program, these aren’t the most flexible functions (you have to use relative paths, and cannot use path short hand like “.” and “..”), but they work pretty well for my purposes. They allow me to play around with Processing from the command line more easily than the standalone command. Here is the same example from above using my functions:

% psetup test_sketch
% echo "size(500,500);" > test_sketch.pde
% prun

I put these functions into my .bash_profile and have been using them for the majority of my Processing development since. Normally, while working on a sketch, I stay within the sketch folder using vim and a combination of Ctrl-Z, fg, and prun to do all my sketch editing and running. The processing-java program will run for as long as the sketch window is open, to terminate it either use Ctrl-C in the terminal or “x” out of the running sketch window.

If you are interesting in working with Processing via the command line, check out the “processing-java” utility, and let me know how it goes. I used OS X, and the 2.0.3 version of Processing for this article. Feel free to post in the comments if you have any improvements, ideas, or questions about using Processing at the command line.