Field

Installing Field for Developers

First, some prerequisites for developing (with) Field:

  • Make sure you're running at least 10.5.5. Preferably, the latest publicly available OS X.
  • Make sure that you have a 64-bit capable Intel-based Mac with Java 6. Field can usually run under 32-bit Java 5, but it's not as well tested.
  • Make sure you have the developer tools for OS X installed (if you haven't, it's quite possible you aren't the intended audience for this project).
  • Install Mercurial — binary pacakges for OS X are available here: http://mercurial.berkwood.com/ (and, if you haven't used it before, take a moment to familiarize yourself with what it is and does - it's not just used for getting Field, it's used as part of Field as well).
  • Make sure that you know that Field's email address is field at openendedgroup dot com.
  • Make sure you have a favorite Java development environment installed. If you don't have a favorite Java development environment installed, again, you might not be the target audience for Field's developer install. OpenEnded is an Eclipse oriented group, but we're not religious about it — just don't expect us to know much about building Field in NetBeans, IntelliJ or anything else.
  • Eclipse has a "Trac Connector" for its Mylyn plugin that you can use to connect to this website's ticket tracking system. If you have access to this bug database (which you'll no doubt get if you ask) then you might be interested in installing these as well. Install Mylyn (if it isn't part of your Eclipse distribution) and the Trac Connector by adding the update site to Eclipse: http://download.eclipse.org/tools/mylyn/update/eX.Y (where X.Y is your eclipse version, say 3.4) (you can always find the latest site from: http://www.eclipse.org/mylyn/downloads/) Add a trac repository http://www.openendedgroup.com:8000/field, with your username and password, access type XML-RPC

Getting Field

To get field, clone the fieldwork repository and the shared workspace repository on openendedgroup.com. How you do this depends on whether or not you have write access to the repository. To just get the version of Field as it currently stands, with read-only access: 

hg clone http://openendedgroup.com:8001 field

If, on the other hand, you are a "committer" then, for now, something like: 

hg clone ssh://public@openendedgroup.com/fieldwork/field field

ought to do it. It should take around 20-25 mins to download the field repository. It's big and it has quite a bit of history.

Building Field

Field comes without .class files in the repository, so you'll have to build it. (But it does ship with .jnilib's already built and in the correct spot). If you are using Eclipse, this is straightforward: import the projects that the repository contains into your workspace (specifically Import->Existing Projects into Workspace->browse->[field directory]). You'll end up with two projects — "fielddevelopment" and "extras". Building them might take Eclipse a while, but both projects should build without error. As of writing the Extras project needs to be built against a 1.6 JVM — make sure that Eclipse has picked a valid 1.6 VM for this project (right-click on the project, Build Path->Configure Build Path). Hopefully recent Eclipses will just do the right thing here.

You should note that the recent Eclipses have been known to hang at this point. Release builds of Eclipse tend to run out of memory. You will probably have to increase the amount of memory that Eclipse can consume. You might have to force quit, and open Eclipse again: everything will eventually be ok.

If you are not using Eclipse then you'll need all of the field.app/Contents/Resources/Java in your (compilation) classpath, and writeMethodAPT.jar on your apt factory path and no doubt something else we're forgetting as well.

Making sure it's all working

From the top level of your field development directory type: 

distribution/application/field.app/Contents/MacOS/JavaApplicationStub

If you are on a Mac with an NVidia card, you can always add -needsFSAA 0 to that command line: it will improve your framerate considerably on older machines.

Making a binary

While distribution/application/field.app looks like a Mac OS X app it really isn't quite — it's a shell. Most of its insides are scattered around the development tree. For efficiency we like to be able to build in Eclipse with no packaging stage while we're working on the innards of Field. You can run it in situ, but if you need to move it around, you should build yourself a real binary: 

ant -f buildRelease.xml distribute

This gets you a free standing .app — just like a binary release.

Integrating it with your own code-base

Take a look at the distribution/application/extensions directory, and its documentation and most importantly the UI for this extensions directory, the Plugin Manager [PaletteOverview#ThePluginandExtensionmanager] — there's even a tutorial video. Specifically, it's likely that you'll want to add an entry that points Field towards your own java class-files and sources (and your own Python sources if you have any).

You could also take a look at RunningField and StartupOptions to familiarize yourself a little with what's actually happening when you run Field, and decide exactly how you want to run it (Marc recommends the command line). Of particular interest is the -field.scratch option which changes which workspace file you are loading on startup (such files are created on demand), and the -main.class option that just uses Field's Launcher to run the class you pass into it. You can open the Field UI in your own code later, or if needs be load and execute sheets without instantiating any UI at all.

The three things you'll want to know

The top three early answers to questions:

  • You right click on the canvas and select "make new visual element" — this gets you a "box" to type python code in.
  • You'll need to from my.java.codebase import * or from still.more.java.code import Wonder to access your codebase. In this case, typing Won and hitting Command-I might help. See CompletionAndInspection.
  • Field saves when you exit (Command-Q, Ctrl-C from the command line, a crash, or your code calling System.exit). The quickest way to exit without saving is a swift kill -9 from the command line. There's also a menu option in the File menu. If you make a mistake, and, worse, end up saving it, don't worry: all versions of your sheet are stored. Go to the History Palette and roll back.

Take a look, next, at the StandardLibrary or, if you are coming over from Processing, the tutorial for Processing.