MapTool build notes for Eclipse
Posted: Sat Apr 24, 2010 9:48 pm
I just put out the MapTool 1.3.b64 build and I learned a lot during that process of how to build that beast! This post/thread will be my ramblings of how it works and what setup may be required.
I will be editing this post over time (paragraphs with blue dates in front of them) so be aware that replies posted below may reference an older version of this post. Caveat emptor.
First, the MapTool SVN repository is just one project. It requires at least one other project checked out into the workspace in order to be built: common.build. Be sure to checkout that project as well.
(Aside: I've done the same thing with a few of the other projects as well, such as the parser, rplib, rplib.resource, and maptool.resource. More about that later.)
You should be able to right-click on MapTool's build.xml and choose Run As -> Ant Build... That will open a dialog where you can fill in various attributes of how to perform the build. I'm going to describe what I did to make it work and why I think there has to be a better approach. In the Run As dialog click on the Classpath tab and you'll notice that ANT has a couple of places where it can pull plugins from. You'll need to add another so click on Add JARs... on the right and navigate to the common.build project's lib directory. Inside there you'll find three JAR files. Add each one to the classpath. One is the Pack200 task, one is the Java implementation of JavaScript (an old one), and I don't know what the third one is (haven't looked). Now you can click the Run button and execute the build. The next time you execute the build.xml those values will already populate the classpath so no changes will be needed.
2010-06-20: I also found that in order to recreate the parser JAR files I needed to have the ANTLR plugin installed in Eclipse. After doing so, it's necessary to right-click on the parser project and select Toggle ANTLR project nature. You'll see a pair of brown antlers appear on the icon next to the project name. This plugin reads the grammar files (such as expression.g) and creates the corresponding LR(1) grammar parser as Java source code. Took me forever to figure this one out.
A build of MapTool puts the resulting files into the ../dist/ directory so that directory should already exist. (It's part of the workspace but you don't want to check it out of SVN or you'll get a HUGE directory full of all revisions of all older builds of all tools! Instead, just create the directory using your OS tools.) You'll have a file called maptool-development.txt (a config file needed by the web site for the WebStart feature), a directory called zip/, and a directory called lib/ (used to hold individual JARs; also for WebStart). I've recently discovered that I can do a simple rsync --ignore-existing -SHavz ./ rptools:www/download/ and any new files will be sent to the proper directory on the web server. (Although I currently need to copy the text file myself. In the future, the text file will be named based on the particular MapTool build, such as maptool-1.3.b64.txt, and as such the --ignore-existing won't affect it. This new naming scheme will allow the web site to serve older versions of MapTool via WebStart, something it can't do right now.)
Another thing I've noticed is how clunky it is to replace a MapTool library with another project. For example, let's say I wanted to fix something in a macro function. I find the code and make some changes, but changes are required in the parser project as well. The parser library is already part of MapTool's build path (in my case, parser-1.1.b20.jar) so I first need to remove that library, then make the parser project a dependency for MapTool. I can now test MapTool and not need the parser JAR at all as long as testing stays within Eclipse (because the parser project will be added to MapTool's classpath).
When I'm ready for a final build, I go into the parser project and right-click on the build.xml and choose Run As -> Ant Build... I verify the parameters (no classpath changes are needed here, since this build file doesn't use Pack200 or other plugins) and click Run. Presto! I have a new JAR file; this one would be parser-1.1.b21.jar. I then copy it back to the MapTool project and turn off the dependency on parser.
I think there must be a better way. Perhaps MapTool should depend on the parser project (so that it gets built as needed, when source code changes) but the project appears higher in the classpath than the (older) JAR file so the JAR file simply isn't used. But even that isn't perfect, since an update to the JAR file won't affect MapTool at all if the project dependency is still there.
There must be a better mouse trap...
I will be editing this post over time (paragraphs with blue dates in front of them) so be aware that replies posted below may reference an older version of this post. Caveat emptor.
First, the MapTool SVN repository is just one project. It requires at least one other project checked out into the workspace in order to be built: common.build. Be sure to checkout that project as well.
(Aside: I've done the same thing with a few of the other projects as well, such as the parser, rplib, rplib.resource, and maptool.resource. More about that later.)
You should be able to right-click on MapTool's build.xml and choose Run As -> Ant Build... That will open a dialog where you can fill in various attributes of how to perform the build. I'm going to describe what I did to make it work and why I think there has to be a better approach. In the Run As dialog click on the Classpath tab and you'll notice that ANT has a couple of places where it can pull plugins from. You'll need to add another so click on Add JARs... on the right and navigate to the common.build project's lib directory. Inside there you'll find three JAR files. Add each one to the classpath. One is the Pack200 task, one is the Java implementation of JavaScript (an old one), and I don't know what the third one is (haven't looked). Now you can click the Run button and execute the build. The next time you execute the build.xml those values will already populate the classpath so no changes will be needed.
2010-06-20: I also found that in order to recreate the parser JAR files I needed to have the ANTLR plugin installed in Eclipse. After doing so, it's necessary to right-click on the parser project and select Toggle ANTLR project nature. You'll see a pair of brown antlers appear on the icon next to the project name. This plugin reads the grammar files (such as expression.g) and creates the corresponding LR(1) grammar parser as Java source code. Took me forever to figure this one out.
A build of MapTool puts the resulting files into the ../dist/ directory so that directory should already exist. (It's part of the workspace but you don't want to check it out of SVN or you'll get a HUGE directory full of all revisions of all older builds of all tools! Instead, just create the directory using your OS tools.) You'll have a file called maptool-development.txt (a config file needed by the web site for the WebStart feature), a directory called zip/, and a directory called lib/ (used to hold individual JARs; also for WebStart). I've recently discovered that I can do a simple rsync --ignore-existing -SHavz ./ rptools:www/download/ and any new files will be sent to the proper directory on the web server. (Although I currently need to copy the text file myself. In the future, the text file will be named based on the particular MapTool build, such as maptool-1.3.b64.txt, and as such the --ignore-existing won't affect it. This new naming scheme will allow the web site to serve older versions of MapTool via WebStart, something it can't do right now.)
Another thing I've noticed is how clunky it is to replace a MapTool library with another project. For example, let's say I wanted to fix something in a macro function. I find the code and make some changes, but changes are required in the parser project as well. The parser library is already part of MapTool's build path (in my case, parser-1.1.b20.jar) so I first need to remove that library, then make the parser project a dependency for MapTool. I can now test MapTool and not need the parser JAR at all as long as testing stays within Eclipse (because the parser project will be added to MapTool's classpath).
When I'm ready for a final build, I go into the parser project and right-click on the build.xml and choose Run As -> Ant Build... I verify the parameters (no classpath changes are needed here, since this build file doesn't use Pack200 or other plugins) and click Run. Presto! I have a new JAR file; this one would be parser-1.1.b21.jar. I then copy it back to the MapTool project and turn off the dependency on parser.
I think there must be a better way. Perhaps MapTool should depend on the parser project (so that it gets built as needed, when source code changes) but the project appears higher in the classpath than the (older) JAR file so the JAR file simply isn't used. But even that isn't perfect, since an update to the JAR file won't affect MapTool at all if the project dependency is still there.
There must be a better mouse trap...