Mac OSX: create a folder dev/eclipse , unzip the download into it inside the ...
Thanks to the people of xampp, it is now very easy to run an Apache webserver ...
Processing 2 Eclipse, and back A recipe for a jump start
Klaus Wassermann Laboratory for Noosynthesis – CAAD - Institute for Technology in Architecture ITA Federal Institute of Technology ETHZ Zurich, Switzerland
[email protected]
CONTENT
I.
Software
1
II. Introducing Processing to Eclipse A. The principle B. Finding File and Folders 1) 2)
Windows Mac OSX
C. Preparing Eclipse
3 3 3 3 3
3
III. A first Project
4
IV. A more complete Example
5
rd
A. Installing a 3 party Library to Processing B. An Example showing code separation C. The Example, using the 3rd party Library
5 5 7
V. Exporting a Package for use in Processing
7
A. Why? B. How? C. The Processing-side of the Export 1) 2)
Installation The Sketch
VI. Resources
7 7 9 9 9
10
I.
SOFTWARE
Type
Tool
Task
Description
Environment for Development
Processing
download
download latest version (1.2) here http://www.processing.org/download/ choose the versions without java.
installation
Windows: unzip to a folder OUTSIDE of c:\program files\... e.g. c:\dev\processing in the folder “dev/processing” create the sub-folder /libraries Mac OSX: start the *.dmg file and follow the instructions
working folders
this is needed to organize your own sketches; it should be OUTSIDE and apart from the program folders, where processing has been installed. It is assumed that you Windows: create a folder D:\programming\processing\sketches Mac OSX: in the folder “Documents”, create a folder dev/processing and therein two folders /sketches and /libraries in the preferences, set the path to the sketch book folders just created
Eclipse
download installation
latest version (“Helios”) here: Eclipse IDE for Java Developers Windows: unzip to a folder OUTSIDE of c:\program files\... e.g. c:\dev\eclipse Mac OSX: create a folder dev/eclipse , unzip the download into it
working folder
inside the eclipse folder, you should find eclipse.exe (win) or eclipse.app Windows: create a folder D:\programming\java Mac OSX: create a folder in the main documents folder dev/workspace later, this will contain the project folders of the eclipse projects
Infrastructure
Java Virtual Machine
download
installation
only Windows: you will need : 1. “Java SDK” (SDK=software development kit), abbr. “JDK” 2. “Java JRE” (JRE = Java runtime environment) it is named “Java Platform, Standard Edition” you get it here: http://www.oracle.com/technetwork/java/javase/downloads/index.html − there are options for “JDK” and “JRE” − create a folder C:\javas, which is deliberately OUTSIDE of the program directory; this will serve as the installations − follow the instructions and activate “automatic actualization” if you meet that question
1
Type Libraries for Processing
Tool
Task download
Description general download site http://www.processing.org/reference/libraries/
install
installation consists just from copying the zip to the “libraries” folder and unpacking it; after rstart of processing, the library will be available; the folders are located in… Windows: Mac OSX: all the 3rd party libraries have to be installed into the directory documents/dev/processing/libraries this folder will contain subfolders, which contain the respective libraries
Export Library for Eclipse
fatjar
download
from the projects website: http://sourceforge.net/projects/fjep/
install
here you will find the instructions for installing it http://fjep.sourceforge.net/ see below; the fatjar is one of the most important infrastructural plugins for Eclipse, if you use it as the environment for developments in processing, and this already in the beginning!
using
WebDevelopment (optional)
xampp
testing webpublishing
You probably want to publish your sketches to the internet, perhaps even on your own website. Before doing so, you usually would like having it tested locally. For this you need a webserver running locally on your computer. Not so long ago this has been a difficult task. Thanks to the people of xampp, it is now very easy to run an Apache webserver and all the rest of the infrastructure for a “local web” on your computer. It is the preferable solution, because everything comes in a nicely bundled package. There are (much more) sophisticated solutions, but xampp is sufficient and the most simple solution. If want to use Java server side, you need a particular java webserver; alternatives are Tomcat (Apache project), Glassfish (independent open source), or Virgo (Eclipse project). For Windows, xampp offers a package which includes the Tomcat
download
http://www.apachefriends.org/en/xampp.html
install
simply follow the instructions. The only issue is for Windows to install it outside the infamous “program files” folder; just select root C:\ or any directory on another drive.
using
You can install now any web-application like blogs or CMS, which is based on php (most of them are)
2
II. INTRODUCING PROCESSING TO ECLIPSE A. The principle Eclipse provides the possibility to integrate arbitrary external libraries, since it is built on top of a dedicated plugin framework (which is named OSGi). Thus we have to prepare a folder for all our plug-ins we will introduce to Eclipse as a standard for all our projects. To achieve that, please complete the following steps: − locate the folder “\eclipse” (e.g. c:\dev\eclipse) − in there, create a directory “libs”, or “xlibs”; any filename should be possible; in reality keep it shorter than 11 characters and do not use blanks! The nice thing with this integration is, that you can use all the processing plugin without the need for declaring it to the Eclipse environment. Thus, you can just install the processing plugins as it is described on the processing website (or below).
B. Finding File and Folders 1) Windows − locate the folder “\processing-1.0.9\lib” (the version number might be different) − select the file “core.jar” − copy this file to the the just prepared folder for external files within the folder branch of Eclipse, which we named “xlibs” above 2) Mac OSX in the application folder you find the file processing.app. This is not just a single file, it is a package. Right-click to icon in the preview pane, then OSX will open a context menu showing the option “show Package Contents”. Select it, then a pseudo-finder window will open, showing the content of the package. Navigate to the folder “Contents/Resources/Java” , where you find the file “core.jar”. Copy this file to the folder “xlibs” which we have created before as a sub-folder of the Eclipse-main folder.
C. Preparing Eclipse Please note that the Eclipse User interface (UI) will be introduced in more detail a bit later. If you start Eclipse for the first time, please jump forward to the section “ABC” and then return to here. Then, we need to create the basic body of a project within Eclipse, please see the next chapter, and return to here. A project can contain all your source files; you can use subfolders to organize your work. If you have created the project, select the project folder in the window left-hand in the Eclipse UI. Then click right-mouse to see the context menu (it will be really a long context meun). Within context menu, locate the last entry which is labeled “Properties”. Select and you are in the properties dialog of the respective project.
To the top of the dialog window you will see 4 page tabs: Source, Projects, Libraries, Order and Export. For now, we need only the “Libraries” page. By default, there will be just one entry: "JRE System Library [J2SE-1.5]" (or 1.6)
3
Right-hand of the dialog window you will find a series of buttons. We need the button with the caption “Add external jars” Click it, and browse to the “xlibs” folder within the branch where “Eclipse” itself resides. Select the folder “core.jar” (you have copied it to their from processings “libs” folder), and insert it. Now you are nearly done! Just restart Eclipse. Remark: this procedure can be used also to “resolve” (better: suppress) circular dependencies between your own libraries. You just need to export your package and then declare it as an external jar for the project, which depends on it.
III.
A FIRST PROJECT
We already have created the basic declaration of a project. In the left panel you will see a folder which bears the name of the project. (please open it to see its content…) If you don’t see any entry, just click right-mouse, and select New::Java Project to create it. Name it “ttt”. Accept all default and press “finish”. Inside of this folder you will find two symbols, one labeled “src”, the other indicates the JRE systems library. We only need the branch labeled “src” . In Eclipse, your sources will be organized in packages. The “package” is an important layer also for exporting all sources which belong together (see below chapter about export). Thus we create a new package: Select the “src” icon and display the context menu (right-click with mouse), select “File::New::Package”, enter the name “smalltest” and press “Finish” Now select the package icon (which is grey at this moment since without any content), and again display the context menu (right-click with mouse, or invoke the top main menu), then select “File::New…::Class” (the :: indicates the next level of your selection) Eclipse will create a java file which contains the desired class. Let us assume you named the class “ttt”, then the java file will be named also “ttt”. If you open the file by double click, you will find it in the main panel in the mid of the screen. It will contain the following code: public class ttt {
}
You will have to extend/replace it by the following basic snippet public /** * * */
class ttt extends PApplet implements Runnable{ class definition for wrapper this wrapper is not needed when coding in processing here in eclipse, it is the only additional code you have to create
public
void setup() {
int applet_width = 250; // set a variable for applet width size(applet_width, 200); // initialize PApplet
4
textFont(createFont("Arial", 12)); // create images from font definitions fill(0); // define color of text System.out.println("hello world :: console"); // write to console text("hello world :: app-window", 5,20); // write to applet, params: (text, x, y) } }
The keyword “PApplet” is underlined in red color, indicating an error, which prevents execution of the program. But Eclipse will help! Just move the pointer above the problem, then you will get available help in the form of a matching suggestion. In our case, the first option is “Import ‘PApplet’ (processing.core)”. Upon selection, the problem will be cured! Now find the following line on top of the program: import processing.core.PApplet;
Now we are ready for running our “Hello World” example, which displays a processing applet from within Eclipse! Run it by pressing the green button containing a white arrow tip; if you are asked, select “run as applet”. On the way, you already will have discovered some goodies of the Eclipse UI. For instance, the notification of errors in the code. First, there is a red underlining, and second, you will see a red tick on the right side of the editor window, If you click to the tick, you directly jump to the faulty code position. If you click right-mouse to the underlined text in the code, you will get offered some possible solutions for your problem!! Another invaluable benefit is code completion. For instance, if you would write “System.out.”, ending with the dot, you probably do not know about all the possible alternatives ot continue, i.e. all the functions available at this point. Just wait a little bit, and Eclipse will offer you the possibilities! In this way, Eclipse helps you to learn Java, or Processing, or even any 3rd party library.
IV.
A MORE COMPLETE EXAMPLE
A. Installing a 3rd party Library to Processing Above we have described how to set up the working folders for processing. Installation of 3rd party libraries consists just in copying the downloaded zip files into that folder “libraries”, unzip it, and restarting processing. (more coming soon)
B. An Example showing code separation If you develop Processing applets in Eclipse, it is a good idea to keep the technical stuff related to starting the applet apart from the logics of your program. In other words, the main class of the program which refers to PApplet should be in one java source file, your actual logics in another. This allows you to export your program correctly into a package. So, we proceed with our example from above, extending the HelloWorld example and showing the organization of files. The goal is, to assemble a particular string (the “logic” of the program) before sending it to the output device (console, or applet window).
5
First select the package “smalltest”, then create a new class “showYourself”, select the file and save everything. You will see the following: package smalltest; public class showYourself{ }
This you should replace/extend by the following code:
package smalltest;
/** * Documentation of showYourself *
* this class does not perform much... * * */ public class showYourself{ public
showYourself( ){ // the constructor of the class
} // any particular methods follow from here
public String myshow( String feedin){ String return_value =""; try{ return_value = "My Hello World "+ feedin;
} // try catch(Exception e){ return_value = ""; e.printStackTrace(); } finally{ } return return_value; } }
There are a number of issues, which you could explore here, e.g. the JavaDoc-style comment (above the class), or the try-catch-finally code pattern, which always is a good idea to protect your code from ugly crashes. Next, we create the connector to the Processing applet . It will look much the same as the ttt.java, with one important change though. Create a new class “simpleMsg” and replace/extend it with this code.
package smalltest;
import processing.core.PApplet;
/** class definition for wrapper * this wrapper is not needed when coding in processing * here in eclipse, it is the only additional code you have to create */ public class simpleMsg extends PApplet implements Runnable{
6
public
void setup() {
showYourself _show = null; int applet_width = 250;
// this declares an instance of our class
// set a variable for applet width
size(applet_width, 200); // initialize PApplet textFont(createFont("Arial", 16)); // create images from font definitions fill(0); // define color of text // this creates a reference of the instance of our class to the class itself _show = new showYourself(); text( _show.myshow(" :)") , 5,40); } }
If you run this, you will see "My Hello World :)" in 16pt Arial in the applaet window; in the console there is no output this time. C. The Example, using the 3rd party Library (coming soon)
V. EXPORTING A PACKAGE FOR USE IN PROCESSING A. Why? Exporting a program from Eclipse into a Processing library offers significant advantages: − simple and painless integration of approved code into other projects − sharing work without giving away your inventions (it is not a bullet proof protection, but for normal people…) − publishing your applet in the internet, since it will run in the browser B. How? Using the fatjar-plugin creating libraries for Processing is a snap! We will now export the small program we have created above. Of course, we are not interested in the ttt.java. What we would like to export is the “simpleMsg”. The goal is to use the function in a way like this text( pshow.myshow(" – from processing!") , 5,40);
to get the output "My Hello World – from processing!". First, select the project “test” in the left pane of the Eclipse UI. Then click right-mouse, and select “Export…”. At the bottom of the list you should find a folder symbol labeled “Other”. If you open it you see an item “Fat Jar Exporter”. Start the export, by selecting this and clicking “Next”. The java project “test” should be already selected. Proceed with “Next” to arrive at the following screen:
7
Note, that you have to change the the name of the jar about to be created into a meaningful one. This name will later appear in the libraries selection list in processing. Pressing “Next” we arrive here, where we select the precise content of our package. We do not export the experimental ttt.java, of course, but also nothing else of any of the other items. In particular, you should NOT select “core.jar”, since this is processing itself. The list offered by fatjar refers to the settings in the “build path” of the project. Of course, if your library is using any other of the listed items, then you should include them too.
8
Clicking “Finish” will create the package file “simpleMsg.jar” in the specified folder.
C. The Processing-side of the Export 1) Installation In the libraries folder for 3rd parties, create a subfolder “simpleMsg”, in there a further subfolder “library”. Copy the file “simpleMsg.jar”, which we have created using the fatjar-Exporter, into this “library” folder. Next we have to create a small text file which contains just a single line : name = simpleMsg. Save this textfile using the name “Export.txt”. Now, on (re-)starting Processing, you should be able to import your library into your sketch. In the top menu select “Sketch::Import Library::simpleMsg”. Selecting it, you will get the following line inserted: import smalltest.*;
“smalltest” has been the name of the package in our Eclipse project. 2) The Sketch Complete this line into the following sketch:
import smalltest.*;
void setup(){ size(300, 200); showYourself pshow = null; pshow = new showYourself() ; textFont(createFont("Arial", 16)); fill(0); text( pshow.myshow("– from processing!") , 25,40); }
As you can see, the declaration and instantiation of the class “showYourself”, which is responsible for the logics of your program/library, looks exactly as it did in Eclipse. Perhaps you already experienced, that writing code in Processing editor is not as quite convenient as in Eclipse :)
9
VI.
RESOURCES
Learning Processing with a lot of examples: http://www.learningprocessing.com/ http://www.openprocessing.org Learning Java directly from the language reference with a lot ot examples: www.java2s.org The tutorial for behavioral flexibility of “virtual agents” on the NooLab website
###
10
