LateralGM:Building_svn - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

This is an archive page from when LateralGM used to reside on Svn. We have since moved to Git, and have updated our build process accordingly, which can be found on the page LateralGM:Building.

Herein I will only cover the official way to build LateralGM from source. Other ways are welcome, and if you wish to document your own way, feel free to update this page with it. In the end, it's as simple as running the Ant task, but getting all the tools together for said task is the tricky part which a large part of this page will be dedicated to.

I used Linux, Ubuntu 9.04-10.10 for this task, so these instructions may require some minor tweaks for different systems.

Prerequisite Tools

You will need several tools. The next sections explain how to obtain them, set them up, and link them together appropriately.

  • Java 6 JDK (must be JDK, because the JRE cannot compile) - This is the compiler for the language that we use. You may use Sun JDK or OpenJDK.
  • Subversion[1] (aka "svn", versions 1.5 or higher) - Subversion is a way to log all the changes to your project and allow multiple people to work on the project simultaneously. We actually only need Svn to get Batik (if you plan to get batik the svn way), since Subclipse and SvnAnt contain their own Svn client.
  • Eclipse (this document assumes 3.5: Galileo, 3.6: Helios, or 3.7: Indigo, but other versions may be similar, and prior versions should work fine) - Eclipse is the IDE we use to work with our files. You can think of it as a really fancy text editor. Aside from Eclipse, the only other documented method of building is from the command line (which still requires the eclipse compiler), so you're on your own if you want to use another IDE.
  • Subclipse 1.6 (eclipse plugin) - Subclipse plugin allows Eclipse to use SVN to fetch LateralGM.
  • Ant (I used 1.7.1, but any version should do, as long as you are careful to remain consistent) - Ant is an xml-script-based way to automate the task of compiling your project.
  • Batik 1.8pre RasterizerTask[2] (I was unable to get 1.7 to work) - Batik is a project for working with SVGs (graphics files). RasterizerTask allows us to use Ant to compile some of our images into more recognizable formats and to add text to them (such as the version number).
  • SvnAnt 1.3.0[3] (This version corresponds with Svn 1.6) - SvnAnt is a way for Ant to use Svn to determine what revision/version number we are on.
  • Liberation Fonts[4] - The set containing the fonts used in the LateralGM splash screen, used in conjunction with Batik.

Notes

[5] [6]

Obtaining the Basic Tools

Java, Subversion, Eclipse, Ant, and Liberation Fonts can be obtained from the Linux repositories (you can use the Software Center) or their respective websites (e.g. for windows users)

  • Software Center: search for JDK, Subversion, Ant, and Eclipse, usually under Developer Tools.
  • apt-get: sudo apt-get install default-jdk subversion eclipse libsvn-java ant ttf-liberation
  • pacman: pacman -Sy openjdk6 subversion eclipse libsvn-java apache-ant ttf-liberation
  • yum: sudo yum install default-jdk subversion eclipse libsvn-java ant ttf-liberation
  • Download the binaries: Oracle JDK 6 (you won't need FX, EE, or NetBeans), Subversion, Eclipse (I'd recommend Eclipse IDE for Java Developers), Ant, and Liberation Fonts.

You may opt for eclipse-ecj instead of eclipse if you want to compile from command line using the Eclipse compiler.

On first run, Eclipse will ask you for a workspace, or a location for it to store projects. This does not matter; it's completely up to you. The default location is usually sufficient.

Sometimes the repository only offers the JRE or JDK 5 or and Eclipse 3.4 and below (usually with older distro versions), in which case you can download from the website instead. Sometimes the Software Center will not install the Eclipse JDT along with Eclipse, so you may have to install it afterwards.

Subclipse must then be installed. How you do this depends on which version of Eclipse you installed, and which version of Subclipse you want. Generally, run Eclipse (if you don't already have it running), and go to Help > Install New Software (or Help > Software Updates). In older versions of Eclipse, you may then need to click the Available Software tab. Assuming Subclipse isn't already listed, click "Add [Site]..." (in 3.5, Galileo, this is near the top, next to the Work With input box), and then enter the Subclipse update site url (which you can find on the Subclipse website) for the Location, so for 1.6 you'd enter http://subclipse.tigris.org/update_1.6.x into the box and click Ok. You should now be at the List screen, and Subversion should now be listed (sometimes a bug may prevent the UI from updating on linux. Try moving it around if nothing shows up). Toggle on the checkbox for Subclipse - you will probably need to expand it (click the triangle to the left of it) and uncheck parts that you don't have the necessary packages for, such as "Subclipse Integration for Mylyn" (if you don't have Mylyn installed), and "Subversion Revision Graph" (if you don't have Graph Tools installed) - and click Next/Install and follow the rest of the screens, and then restart Eclipse when it tells you to.

Checking out LateralGM

Our SVN repository is located at (although clicking that link won't do you a lot of good unless you want to download the files one at a time... you usually need to point your subversion client to that url), but consists of two projects: our Action library icon set (which you probably won't need), and LateralGM. LateralGM is further subdivided into trunk, branches, and tags - you'll probably only be grabbing the trunk.

Command Line

svn co `` lateralgm

Eclipse

Ensure that Eclipse is running. If you have a "Welcome" screen, you can simply X out of it (top left, it will be a tab). We must now create a New > Other. You can access this from the File > New > Other menu, or the button just below it with tooltip text "New", or by right clicking in the Package Explorer area and selecting New > Other. This will bring up the New Wizard, which will list several folders of things you can create. One of those folders should be called SVN (if you do not have an SVN folder, Subclipse did not install properly). Expand it, select "Checkout Projects from SVN" and click "Next", "Create a new Repository Location", Next, enter the LateralGM SVN repository location: and click Next. If you receive an error about an Invalid Resource or some similar nonsense, it may be because our svn host is down. Simply cancel out and try again later (may be 15 minutes, may be a day. You might try checking on the general status of SourceForge). At this point you should see a tree with a root and 3 folders, labeled "branches", "tags", and "trunk". If you want a specific branch or tag, expand that folder and select the one you want. But most likely, you'll just want the trunk, so select "trunk" and click Finish (if you click Next, the next few steps are more advanced checkout settings and allow you to change the default project name to something other than "LateralGM"). After this, it will start downloading the information from the server, so this may take a minute.

At this point, you have everything you need to modify/run it. Simply right click the Project in the Project Explorer (the one named LateralGM), and select Run As > Java Application. Of course, running it is completely optional. If you run it this way, most likely no plugins will be loaded, because it won't know where to locate the "plugins" folder.

Getting SvnAnt and Batik

You can skip these steps if you just wish to make a raw jar without Batik or SvnAnt.

The Easy Way

Because it's a royal pain to fetch SvnAnt, figure out which files you need and which ones you don't, and since Batik either suffers from the same plague, or doesn't even have a precompiled version of RasterizerTask and the necessary files which works... so we've saved you the trouble and gathered up the necessary Ant jars for you. This may or may not work for you, but it's worked for all of the computers I've tested it on.

ant_libs.zip or A mirror (4 MB)

If anybody wishes to mirror it, that would be greatly appreciated.

The Hard Way

Getting SvnAnt

SvnAnt is needed for ant to be able to determine what revision you're using, and populate certain files with this information. To get SvnAnt, first, you have to download SvnAnt 1.3.0. Once you've downloaded and unpacked that, you will need some of the jars in the lib folder. Namely, svnant.jar, svnClientAdapter.jar, svnjavahl.jar, and svnkit.jar (if available). Copy these files over into a folder, perhaps named ant_libs.

Getting Batik

Open up a terminal or command prompt, and go to a directory where you'd like to store batik for the time being.

Locating Java

Batik has trouble locating Java, so we'll need to set up our JAVA_HOME variable to contain wherever Java is located. Under Windows, you chose the location when you downloaded and installed Java, most likely somewhere in Program Files. Under Linux, you'll have to hunt it down. First I'd do a which javac to find out where the javac compiler is located. Let's suppose that outputs /usr/bin/javac but this is just a link, so now we need to figure out where that link points to, ls -l /usr/bin/javac should print it out at the very end. For me, it prints out /etc/alternatives/javac but this is also a link, so I'll pass it through ls again ls -l /etc/alternatives/java and get /usr/lib/jvm/java-6-sun/bin/javac which is finally the location of javac. We can confirm that it's not a link because if we run ls on it again, it will just print out the same location. If anybody knows a better way of locating java, feel free to let me know or edit this page. JAVA_HOME must be set to the directory just before the bin folder that contains javac. So for me, it would be /usr/lib/jvm/java-6-sun so under linux I would run the following command to set my JAVA_HOME variable: export JAVA_HOME=/usr/lib/jvm/java-6-sun Notice that we have to keep this terminal open now, otherwise our JAVA_HOME variable will go away. We'll only need it long enough to compile Batik, though. Under windows, you can just set an environmental variable and restart the command prompt to detect the changes.

Batik

All that is just because Ant has trouble finding Java otherwise, which makes it difficult to compile Batik. Now we're ready for Batik.

The following commands may each take a moment to complete. First we'll download batik from the server, then we'll go inside the newly created Batik directory and tell Ant to compile it, then jar it. Then we'll move to the RasterizerTask and compile and jar that. At the end, we'll grab up the jars we need and stick them in an ant_libs folder just outside the batik folder. These commands tend to be output intensive, even printing out a lot of warnings. This can be safely ignored, but keep your eyes open for anything that says "Error" in bright red letters.

    mkdir ant_libs
    svn co http://svn.apache.org/repos/asf/xmlgraphics/batik/trunk/ batik
    cd batik
    ant compile
    ant all-jar
    cd contrib/rasterizertask
    ant -lib ../../batik-1.8pre/lib/batik-all.jar compile
    ant jar
    cp build/lib/RasterizerTask.jar ../../../ant_libs/
    cd ../..
    cp batik-1.8pre/lib/batik-all.jar ../ant_libs/
    cp lib/xml-apis-ext.jar ../ant_libs/

Grab up the jars inside of the ant_libs folder and put them together with the jars from SvnAnt. These jars are the end product that we'll be using in the next step. Once you have these jars, you can pretty much safely delete SvnAnt and Batik.

You may notice that your jars are a different size from the ones I provide. This is because some of the jars contain extraneous packages which I was able to prune out to keep the filesize down.

Notice: A batik bug was recently corrected in batik revision 946961 which affected the ability to construct the splash screen. Between batik revisions of 700000 and 800000, a null pointer problem (which existed in 1.7) went away, and later a problem of extraneous, empty IDAT chunks was introduced, and was not fixed until a very recent revision 946961 (date: 2010-06-21). As a result, if you use revision 700000 or prior, ANT will not compile, complaining about a NullPointerException. If you use any revision between 800000 and 946961, ANT will compile, but the splash screen will not display (due to the aforementioned IDAT bug). Although I'm not sure which revision finally solved the NullPointerException, nor which revision introduced the IDAT bug, I've found that revision 750000 does not seem to exhibit either of these issues. As such, if you experience this problem, make sure to update to revision 946961 or later (e.g. the head revision should work).

Informing Ant of SvnAnt and Batik tasks

From the command line, linking the tasks is a simple matter of passing -lib path/to/ant_libs to ant.

For eclipse, we need to set some things up in the interface.

The recommended method is to use Eclipse. Eclipse, however, has its own Ant, which we don't want it to use, since Batik was compiled for our specific ant (thank the Batik devs for this one). So open Eclipse if you don't already have it open, and make sure you already have the LateralGM project checked out (from a previous step). Now go to Window > Preferences, expand Ant, and click Runtime.

Under Classpath tab, highlight/select Ant Home Entries. Then click the Ant Home button on the right, and hunt down wherever you have Ant installed. For linux users, consider the trick I used to hunt down where java was installed (using command line, which, and ls -l to resolve links). For me, it's located at /usr/share/ant/bin/ant which means that I would select /usr/share/ant. For arch, it's usually found at /usr/share/java/apache-ant/bin/ant

Now to add our SvnAnt and Batik tasks (or you can skip this step if you just want a raw jar). Under Classpath tab, highlight/select Global Entries, and then click Add External Jars. Browse to our ant_libs folder (or wherever you unzipped ant_libs.zip to), and select all the jars in it, and click OK. Then click Apply, and Ok. Now Ant should be aware of SvnAnt and Batik

Running Ant

Finally, we're ready to build our project into a jar.

Command Line, Default JDK

If you wish to compile with a command line, you should just be able to call

cd path/to/LateralGM/build.xml
ant -lib path/to/ant_libs

If you experience strange errors, usually java compiler errors about imports not being found, try ant clean first and then retry.

In LateralGM revisions prior to r498 it is necessary to call ant compile before the normal call to ant. In r498, a normal call to ant will now ensure that it is compiled.

Unfortunately, you'll probably encounter some errors with the default compiler due to Java bug 6302954, so you're encouraged to either use the Eclipse method or at least the Eclipse JDK.

Command Line, Eclipse JDK

You'll need to get some eclipse libraries. Namely, jdtCompilerAdapter.jar and org.eclipse.jdt.core_3.5.2.v_981_R35x.jar which are currently mirrored here (4 MB) (or you can use your own if you have eclipse or eclipse-ecj installed). Put them in a folder called eclipse_libs, or add two -lib calls to locate both of them. Then you'll need to specify the compiler with the -Dbuild.compiler option set to org.eclipse.jdt.core.JDTCompilerAdapter.

cd path/to/LateralGM/build.xml
ant -lib path/to/ant_libs -lib path/to/eclipse_libs -Dbuild.compiler=org.eclipse.jdt.core.JDTCompilerAdapter

Prior to LateralGM r498 it is necessary to call the compile target before calling ant's default target. Here's what that would look like:

cd path/to/LateralGM/build.xml
ant -lib path/to/eclipse_libs -Dbuild.compiler=org.eclipse.jdt.core.JDTCompilerAdapter compile
ant -lib path/to/ant_libs

Again, if you run into weird errors like Java import not found or something, try doing an ant clean first and then retry.

To build another target, such as jar or jar-all for building a jar without batik or svnkit, simply append the target name to the last call to ant. Instead of ant -lib path/to/ant_libs simply do ant -lib path/to/ant_libs jar-all

Eclipse

Expand the LateralGM project, and scroll down until you find build.xml. If you have SvnAnt and Batik installed, then all you need to do now is Right Click on build.xml, Run As > Ant Build (the first option, with the shortcut keys. Don't ask me why there's 2 options). If everything is set up right, you should see some text at the bottom pane telling you what its doing, and hopefully you don't get any red Error or Failure messages. It should end with "Build Successful", and you'll have a newly created LateralGM jar on your desktop (filename may vary), ready for distribution.

There are some other ways you can compile the project using our build.xml. Open up build.xml (by double clicking it), and you'll see some XML in the middle pane. The second line is the one that is of interest to us. Notice the "build". Scroll down and read the comments to see the different compiling options. The only other more common one would be "jar" or "jar-all" which constructs a raw jar without needing SvnAnt or Batik (instead, it uses a default splash screen image with no revision information on it, but the About box will say $$rev$$ indicating where the svn revision would have otherwise been inserted). A raw jar is still as usable as a fully build jar, but due to the aforementioned reasons, it's not really fit for distribution.

  5. Batik and SvnAnt are optional (and, by extension, so is Liberation Fonts), but strongly recommended. If either are missing, you will only be able to construct a jar with a default graphic and the About Box will say "$$rev$$" in it where the SVN revision would normally go. This is called a "raw jar". A raw jar can still be used to run LateralGM, it's just less desirable for distribution because the revision number is useful for debugging.

  6. Subversion is optional, but strongly recommended. Here, it is only used to fetch Batik in case you can't use the prepackaged version I have provided. In general, I find it's a very useful tool to have around, since many projects can be checked out through SVN.