The Basics

Bleeding Edge Build Instructions

Ants in your pants? House on fire? Coffee getting cold? Crank out a build right away:

• Install Java
• Install Eclipse
• Install Subclipse
• Install m2e Connector
• Check out latest SVN version
• Build the project

Project Overview

Welcome to the development wiki for the Forge project. This document aims to answer questions about Forge building and testing. There's something everyone can help with:

• Game Testers: Testers simply play the game, but take the time to report bugs so the developers can fix them.

Startup suggestion: Here's how to report bugs quickly and easily.

• Code Contributors: Contributors are comfortable modifying/creating card files and fixing minor bugs.

Startup suggestion: After you complete your build, you may want to look at the card scripting API.

• Java Developers: Developers work with the Java source directly, implementing game features and publishing changes.

Startup suggestion: The Forge team recommends these plugins at present.

Whatever your interest, the first step is to register/login on the slightlymagic.net forum.

About this document

Licensing

This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.

Discussion/Editing

Discussion and comments at Discussion area or in the forum. It is good practice to discuss changes before they become permanent.

Editing directions using the Mediawiki syntax can be found here.

Sections to be edited are marked "Section Incomplete", "TODO", or similar.

Testing Notes

The Windows portions of these instructions have been tested with Windows XP. Versions of Windows older than XP may not accept forward slashes ( / ) in folder paths; in that case, you must use backslashes ( \ ) instead. There may be other variations.

The Mac OS portions of these instructions have been tested on Mac OS X Snow Leopard by Chris H. They may also work with Lion or later.

Contributors

Special thanks go (in alphabetical order) . . .

• to Doublestrike who restructured and updated this document for better usability.
• to Braids, who revised this document over and over from others' knowledge and fiddling with Eclipse.
• to Chris H., who provided Mac OS specific instructions and corrections.
• to jeffwadsworth who provided corrections.
• to Rob Cashwalker, who provided the first draft of what became this document.
• to everyone else who edited this document on the wiki at slightlymagic.net.

Installations

This section deals with installation details for the various software used in the common development environment.

Java

Java is the programming language which Forge is written in. It's got its own runtime environment that allows the same program to be run on any operating system. For development, it is best to install a Java Development Kit, or JDK, instead of a JRE or other JVM if possible.

Windows-Specific Instructions

Download Java from this site. If you want 64-bit Java, you must visit the site with a 64-bit browser (currently Internet Explorer is the most popular option).

You could download a JRE or a JDK. The JRE allows you to run Java programs only. The JDK includes a JRE and several development tools, such as a compiler, which you'll need for development.

There's many tutorials on the Net that do a great job of explaining this install. Basically, run the installer.

Testing

You can test your install from the command line by entering java -version. You should get something like:

java version "1.6.0_27-ea"
Java(TM) SE Runtime Environment (build 1.6.0_27-ea-b03)
Java HotSpot(TM) Client VM (build 20.2-b03, mixed mode, sharing)

If you've run the installer, but the test doesn't work, you'll need to show your computer where to look for the Java compiler. Find your system environment variables and append ;path-to-java-install/bin to the end of the PATH variable. You may need to log off/on before it works.

Portability (Optional)

Both flavors of Java (x86 and x64) can be installed to a USB drive to move your dev environment between operating systems. A batch file must be created to (temporarily) modify the PATH variable of the host machine, with this line of code included:

SET path=path-to-jdk-folder\bin;!path!

A GOTO block can be set to test for OS architecture using the following line:

if %processor_architecture:86=%==%processor_architecture%

Macintosh-Specific Instructions

Java comes pre-installed on versions of Mac OS X Snow Leopard and earlier. Starting with the Lion OS java is now a separate download. You can download the java installer from the Apple - Support - Downloads page http://support.apple.com/kb/DL1421.

Double click the JavaForMacOSX10.7.dmg file and then double click the JavaForMacOSX10.7.pkg package file to launch the installer. Follow the installer instructions.

Testing

You can test your install from the Terminal.app application that is located in your /Applications/Utilities/ folder by entering java -version into the terminal window. You should get something like:

java version "1.6.0_26"
Java(TM) SE Runtime Environment (build 1.6.0_26-b03-383-11A511c)
Java HotSpot(TM) 64-Bit Server VM (build 20.1-b02-383, mixed mode)

Helpful Links

Although we officially recommend a JDK, the curious may be interested in how the softwares differ. See JRE vs. JDK vs. JVM.

Eclipse

Eclipse is the most popular IDE for programming Java. Many developers also recommend NetBeans, but current documentation will only cover Eclipse applications.

The following instructions are for "Eclipse Classic" 3.7 (Indigo). Upgrading to the latest version is recommended.

For Windows, save the zip file to a folder. For Mac OS, the 64 bit version may be the better choice than the 32 bit version. The Mac OS archives are .tar.gz files rather than .zip files.

These instructions are highly specific to your computer's operating system.

Windows-Specific Instructions

1. Right-click the zip file you just downloaded and choose Explore. The eclipse-SDK... window opens.
2. Right-click the eclipse folder and choose Copy.
3. Browse to the parent folder where you would like to install eclipse, such as "C:/Program Files" or "/usr/local".
4. Choose the Edit menu, then Paste.
5. Create a shortcut to "C:/Program Files/eclipse/eclipse.exe" (or wherever you installed Eclipse) on your desktop or in your Start Menu.
6. Run Eclipse.
7. When prompted for a workspace, you can use the default path, place a check next to Use this as the default and do not ask again, and click OK. However, if you intend to use Eclipse for C or C++ programming, you may wish to Browse to and create a workspace folder that does not have any spaces in its path. You can change this setting later if you wish. If you find this step confusing, just accept the default.

Portability (Optional)

Eclipse can be run from a USB drive. If your Java installation is also portable, you will need to pass the address of the JRE for Eclipse to use. You'll also need to tell Eclipse where your preferred workspace is.

eclipse.exe -vm path-to-jdk-folder\bin -data path-to-workspace

Note that all installs must be run from the batch file to ensure proper environment is being used.

You can confirm that all is working as you want in "About -> About Eclipse SDK -> Installation Details -> Configuration".

Macintosh-Specific Instructions

1. Double click on the archive and the Mac OS will use it's built-in Archive Utility to decompress the archive. Once the archive is extracted you will have a folder named "eclipse". Move this folder to your Applications folder.
2. You can drag the Eclipse.app icon to your dock to make it easier to launch the Eclipse application.
3. Run Ecliipse.
4. When prompted for a workspace you can select the default path and the workspace folder will be placed inside of your documents folder. You can click on the Browse button to place your workspace folder elsewhere.

Helpful Links

Eclipse Homepage

Subversion

Subversion is a version control system, often abbreviated SVN. It allows users to archive consecutive versions of a project as minor changes are introduced. If there's a problem, the published version can be rolled back as needed.

Although installing the standalone Subversion tool may not be required in your particular situation, it is strongly recommended for the following reasons:

1. Some versions of Subclipse simply will not run without it.
2. When reporting bugs from within a Forge that you compiled yourself, Forge will attempt to run the "svnversion" command to automatically fill in the SVN Rev field.
3. Sometimes Subclipse runs into problems that it cannot solve by itself. The command line tool is helpful for getting around such problems.

Windows Instructions

1. Download the zip file here.
2. Unpack the file to your preferred location on your hard drive.
3. Find your system environment variables and append ;path-to-subversion-install/bin to the end of the PATH variable.
   • You may need to log off/on before it works.

Testing

You can test your install from the command line by entering svn --version. You should get something like:

svn, version 1.6.17 (r1128011)
compiled Jun  2 2011, 23:35:08
Copyright (C) 2000-2009 CollabNet.
Subversion is open source software, see http://subversion.apache.org/
This product includes software developed by CollabNet (http://www.Collab.Net/).

Portability (Optional)

Subversion can be succesfully run from a USB drive. Add the following line to your batch file:

SET path=path-to-subversion-unpacked\bin;!path!

Macintosh Instructions

Download the Subversion v1.6.17 binaries for Snow Leopard (Mac OS X 10.6) at CollabNet "http://www.open.collab.net/downloads/community/". This version is a universal build (ppc, i386 and x86_64). This dmg archive contains a package. Double click on the package to install Subversion.

Currently as of August 13, 2011 there are no Subversion packages that will install onto the new Lion OS. Subversion will only install onto Snow Leopard or earlier. If you installed Subversion onto Snow Leopard or earlier and then update the OS to Lion then the Subversion software will operate successfully.

Testing

You can test your install from the Terminal by entering svn --version. You should get something like:

svn, version 1.6.16 (r1073529)
  compiled Jun 13 2011, 15:54:33
Copyright (C) 2000-2009 CollabNet.
Subversion is open source software, see http://subversion.apache.org/
This product includes software developed by CollabNet (http://www.Collab.Net/).

Helpful Links

Subversion Homepage

Subclipse

Subclipse is a plugin that integrates your computer's Subversion client into the Eclipse user interface.

These instructions should work on any OS.

1. In Eclipse, go to the Help menu and choose Install New Software... The Install window appears.
2. In the text box labeled Work with: paste in "http://subclipse.tigris.org/update_1.6.x".
3. Click Add and wait a moment while the list populates.
4. Click Select All, then Next. Wait some more while the license information is transferred.
5. Read the license text(s).
6. If you accept the terms of the license(s), click I accept the terms of the license agreement. If you do not accept the terms, you will have to stop here.
7. Click Finish. Eclipse should show that it is "Installing Software" in the lower right corner.
8. The Software Updates window appears. Click Restart Now.
9. Wait for Eclipse to finish restarting.

Subclipse apparently includes JavaHL under Windows 32 bit and you may not need to install it separately at this point. Subclipse should work OK if you are using a 32 bit JVM.

If you need to use a 64 bit JVM then you should download and install a 64 bit version of JavaHL. You can try SlickSVN at "http://www.sliksvn.com/en/download" as an option.

Note that there is another plugin, Subversive, that offers the same functionality in a different flavor, if you want options. For now, Subclipse is recommended by the Forge Dev team.

Testing

You can confirm installed software in About -> About Eclipse SDK -> Installation Details -> Installed Software.

You should now have File -> Import -> SVN -> Checkout Project From SVN available.

Also, you should now be able to use Window -> Open Perspective -> Other... -> SVN Repository Exploring.

Branches

SVN uses a concept called "branches", which are lines of development independent of the main trunk of the project. A few parts of the project may use this feature.

To create a branch in Eclipse/Subclipse:

1. Open the project you wish to branch in your Eclipse workspace
2. Navigate to the folder you wish to branch, using either the package explorer or project explorer
3. Right click on the folder, this should bring up the menu with Team
4. Select Branch... from the Team submenu. This will bring up the Create Branch GUI
5. Enter a name Branch: box" (Note: the branch will be created underneath "http://svn.slightlymagic.net/forge/branches")
6. If you already have modification in your work space, select Use the working copy as it is from the options menu
7. If you want to create a branch from the head revision of the Trunk, select Use the repository version
8. Enter a comment in the Comment box
9. Look through the files and folders listed in the Resource. This box lists all the un-versioned files and folders in the workspace that are not ignored
10. In the Resource list box, select only those files that you want added to your branch in the SVN repository. (Note: Unchecked files will remain as un-versioned in your workspace)
11. Check the Start working in the branch check box if you want Subclipse to switch your workspace to the new branch. Otherwise follow the directions below for switching between branches
12. Click Ok to finish making the branch (Note: this may take some time if you're adding a bunch of new files)

Tips and recommendations for creating branch

• For a major feature or refactor branch, branching from the top level of the Forge project is recommended
• To setup a branch for something like a pre-release cards, only the sub-folder can be used as a branch
• Branches can be made from a workspace that contain modifications that have not been checked in
• It a good practice to update your workspace from the Trunk before creating a branch

To switch to a branch in Eclipse/Subclipse:

1. Navigate to the folder you wish to branch, using either the package explorer or project explorer
2. Right click on the folder, this should bring up the menu with Team
3. Select Switch... from the Team submenu. This will bring up the Switch to GUI
4. Enter "http://svn.slightlymagic.net/forge/branches/XXX" in the URL: box (or you can browse to it by clicking on the the "Browse..." button) , where "XXX" is the relative address of the target directory.

To switch back to the trunk:

1. Repeat steps 1-3 from above
2. Enter "http://svn.slightlymagic.net/forge/trunk/XXX" in the URL: box, where "XXX" is the relative address of the target directory.

Once you have done this once, the pull down for the URL should be populated with these two choices.

Updating a branch from the Trunk in Eclipse/Subclipse:

1. Navigate to the folder you wish to update, using either the package explorer or project explorer
2. Update your branch checkout and commit any outstanding changes.
3. Right click on the folder, this should bring up the menu with Team
4. Select Merge... from the Team submenu. This will bring up the Merge GUI
5. Select the URL Tab
6. Enter "http://svn.slightlymagic.net/forge/trunk/XXX" in the URL: box, where "XXX" is the relative address of the target directory.
7. Select Revision: in the Revisions Radio Box, and enter the range of revision from last time the branch was updated to the current HEAD revision of the trunk i.e LAST_MERGED_REVISION-HEAD_REVISION
8. If you want to see what the merge will do without making any actual changes, you can press the preview button.
9. Once you are to proceed with the actual merge, press OK. This will bring up the "Team Synchronizing" Perspective. (Note: This operation may take a while if a large number of file are effected)
10. The files that were modified or added by the merge should be displayed in the Synchronize tab in the Team Synchronizing Perspective.
11. Address any conflicts that may have occurred from the merge.
12. Commit the changes from the update to the branch. Make sure to note the revision used in the merge.

Tips and recommendations for updating a branch

• Ideally, the message when the updates are committed to the branch should be in the form:

  "Merged changes from trunk to <Branch Name>: LAST_MERGED_REVISION-HEAD_REVISION"

• This allows users to easily find the revisions to use for later updates

Portability (Optional, Windows only)

Only a 32-bit version of Subclipse could be run from a USB drive at the time of this writing. A 64-bit version requires 64-bit JavaHL libraries.

Helpful Links

Subclipse Tutorial

Maven

Maven is a tool used for publishing versions of Forge for public release. It automates and standardizes the process so best practices are followed and project structure is consistent.

You do not need to install Maven unless you plan on being part of this process.

Windows Instructions

1. Download the zip file here.
2. Unpack the file to your preferred location on your hard drive.
3. Find your system environment variables and append ;path-to-maven-install/bin to the end of the PATH variable.
   • You may need to log off/on before it works.

Testing

From the command line, mvn --version should produce something similar to

Apache Maven 3.0.3 (r1075438; 2011-03-01 01:31:09+0800)
Maven home: C:\path-to-maven\bin\..
Java version: 1.6.0_27-ea, vendor: Sun Microsystems Inc.
Java home: C:\path-to-jdk-folder\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 7", version: "6.1", arch: "x86", family: "windows"

Portability (Optional)

Maven can be run from a USB drive. Change the JAVA_HOME variable, and add the \bin to the PATH variable. Add the following lines to your batch file:

SET java_home=path-to-jdk-folder
SET path=%java_home%\bin;!path!

Mac OS Instructions

Maven should already be installed.

Testing

From the Terminal application, mvn --version should produce something similar to

Apache Maven 3.0.3 (r1075438; 2011-03-01 01:31:09+0800)
Maven home: C:\path-to-maven\bin\..
Java version: 1.6.0_27-ea, vendor: Sun Microsystems Inc.
Java home: C:\path-to-jdk-folder\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 7", version: "6.1", arch: "x86", family: "windows"

Helpful Links

Installation Instructions

m2e Plugin

m2e is a required plugin that integrates your computer's Maven client into the Eclipse user interface. It is responsible for downloading the latest third-party jars for ordinary Java compilation of Forge.

These instructions will work on any OS.

1. In Eclipse, go to the Help menu and choose Install New Software... The Install window appears.
2. In the text box labeled Work with:, use the drop down menu to select --All Available Sites--.
   • Wait a moment while the list populates.
3. In the type filter text field, type m2e.
4. Select m2e - Maven Integration for Eclipse, then click Next.
   • Wait while the license information is transferred.
5. Read the license text(s).
6. If you accept the terms of the license(s), click I accept the terms of the license agreement. If you do not accept the terms, you will have to stop here.
7. Click Finish. Eclipse should show that it is "Installing Software" in the lower right corner.
8. The Software Updates window appears. Click Restart Now.
9. Wait for Eclipse to finish restarting.

Testing

You can confirm installed software in About -> About Eclipse SDK -> Installation Details -> Installed Software. You should now have File -> Import -> Maven -> ... available.

Portability (Optional, Windows only)

(Section incomplete.)

m2e Plugin Connectors

The m2e plugin must have a connector installed to work with various SCM repositories. Connectors can be found as follows.

SVN Connector

1. Navigate to File -> Import...
2. Expand the Maven folder
3. Select Check Out Maven Projects from SCM and click Next.
4. In the dialog window that opens, click Find more SCM connectors in the m2e Marketplace
   • It's on the lower right side of the window.
5. Search for m2e-svn and select. Click Finish.
6. Continue with the standard install procedure and restart Eclipse.

Testing

You can confirm installed software in About -> About Eclipse SDK -> Installation Details -> Installed Software.

Working with the project

Checkout the SVN Repository

If you're new to SVN, it's a good idea to have a look at Forge SVN site to get a grasp of what's going on.

Note: Don't use the Google SVN mentioned in the threads!

1. Launch Eclipse.
2. Select the File menu command and then the Import... menu command.
3. At the Import dialog select SVN, then Checkout Projects from SVN. Click Next >.
4. At the Checkout from SVN dialog select the radio button Create a new repository location. Click Next >.
5. Paste in the Url "http://svn.slightlymagic.net/forge/trunk" into the text box labeled Location Url. Click Next >.
6. You are asked to select the folder to be checked out from SVN. Select the top level folder labeled http://svn.slightlymagic.net/forge/trunk. Click Finish.
7. It will take some time to import the project. You will see your progress displayed in a dialog labeled SVN Checkout.
   • Note: In the "Console" tab, the "Open Console" button has an "SVN Console" option. This console shows each SVN command and transaction.

At this point, you should have a project folder named "ForgeSVN" or something similar in your Eclipse workspace. While in Eclipse, you should select Window -> Show View -> Project Explorer. With the Project Explorer view active you can navigate the folders and find the individual contents of the ForgeSVN project.

First time checkout

You've checked out your repository for the first time. It's got hundreds of errors. What's going on?

Important: As part of the initial checkout, you must update the Maven dependencies for your checked out project.

1. Right click your Forge project (you may have named it ForgeSVN), click Maven, then Update dependencies. The Update Maven Dependencies Window appears.
2. Make sure that your Forge project's checkbox is checked, then click OK.

Command Line Usage

Occasionally, command line use of Subversion may be required (maybe for Troubleshooting). This line will get you started:

svn checkout http://svn.slightlymagic.net/forge/trunk -r HEAD --depth=infinity --force

Also, you may want to check out only one directory. Here's a starting point:

svn checkout --non-recursive http://svn.slightlymagic.net/forge/trunk/path-to-dir 

For more commands, have a look at http://svnbook.red-bean.com/en/1.5/svn.ref.svn.html

Building and Exporting the Project

1. Open Eclipse IDE.
   • You should have a project folder named "ForgeSVN" or something similar in your Eclipse workspace.
2. Click on and highlight the ForgeSVN project folder. Right click and there should be a Run As -> Java Application choice.
3. Wait a bit for the list of Java classes. Choose the one named Gui_NewGame - Forge.
4. The Forge New Game window should appear after a few seconds. Give it time.
   • After it appears, you can close this window if you want.
5. Select File -> Export... -> Java -> Runable JAR file.
6. Select the Launch configuration and Extract required libraries into generated JAR options.
7. Use Browse to choose the Export destination. Click on finish.
   • There may then appear several warnings which are not very important. A JAR file is now available to launch the game.
8. You can copy the necessary files from the forge project, the new JAR file, your previous pics folder, decks folder and questData file over (place the files into a separate folder and not into the forgeSVN project folder) and you should be up to date at that point. (Section incomplete: what necessary files?)

Scripting Cards

http://www.slightlymagic.net/wiki/Forge_API

http://www.slightlymagic.net/wiki/Forge_Scriptables

http://www.slightlymagic.net/wiki/Forge_Upcoming

(Section incomplete.)

Tracking Bugs

1. Sign up for cardforge's Mantis bug tracker.
2. Send a Private Message to Rob Cashwalker that you've registered for Mantis.

(Section incomplete.)

Committing changes to the repository

You'll need to become a member of the Developers - Forge group in your slightlymagic.net control panel before you can commit changes. Here's how:

1. Sign in to your account at CCGH.
2. Go to your User Control Panel and click on Usergroups. Click on the Developers - Forge radio button. Select Join selected and then click the Submit button.
3. It may take up to a day or two before you notice that you have the ability to make a commit to the SVN. Please be patient.

When you are ready to commit, there are three big rules to follow, more or less:

1. Commits with errors are not welcome. Make sure you're working with the very latest release, and that you have no errors. Then, commit away. There's pretty much no excuse for a commit with errors.
2. So you don't have errors, be sure to update your local version to HEAD quite often. Many users have several versions of the repository on their computer, so a working version doesn't mix with the base, but that's up to you.
3. Commit often, for small chunks of work. This ensures your efforts squeeze in there before they're steamrolled by several other developers over hours or days. If that happens, you'll have more errors than you know what to do with, which can be demoralising.

Of course, changes you make will probably be included in the release. Please read the next section for more specific details about releases to the public.

Release Schedule and Guidelines

1. All releases are considered as a beta build. Forge is a work in progress and it is buggy and unfinished. There will be releases that are more unstable than others.
2. Friday may be the best day of the week to release future betas. This gives members of the dev team the following weekend to submit material that may prove to be disruptive to the code base. In the past we have tried other days of the week including Mondays. It may be best to standardize on a specific day of the week if possible.
3. Typically, builds will be released to the general public bi-weekly. Occasionally, circumstances might require this schedule to be stretched or hurried.
4. The Nightly builds provide the user base with a build that includes recent submissions to the SVN code base. Nightly builds can be viewed as replacement to the beta releases. Nightly builds include all of the files that are found in the beta release. We can not guarantee that a new nightly build will appear on a daily basis as unforeseen circumstances can prevent this from occurring. Several Nightly builds per week may be a more realistic approach over the long term.
5. Major changes/submissions to the code base that may be disruptive should be merged into the SVN on the weekend following a beta release. This will give people a chance to find and to fix any problems which may become apparent after a merge. It may be difficult to predict which merges are disruptive and which ones are safe. It could be viewed as something of a crap shoot.
6. Minor new material and bug fixes can be submitted at all times between beta releases. Granted, what is meant to be a minor submission or a minor bug fix could leave the code base in a problematic state. Stuff happens.
7. Major changes to the code base should be discussed with other members of the dev team on the dev topic in advance to submitting the changes to the SVN.
8. The release dev should try to make sure that the code will compile error free and that the forge jar will launch to the New Game window without an error exception prior to running the Maven build and release script. Additional testing beyond this may be difficult.
9. Devs should make sure that their submissions to the SVN allows the project to compile error free. In the past we have had several broken builds. We should try to work together to get the problems resolved.
10. The release dev should try to post a message one to three days in advance that we are nearing the next beta release. This will give the dev team enough notice to "stop the presses" until someone can address an issue that needs to be resolved before the release.
11. The beta release announcements do not need the cryptic commit logs included in the release message. We can continue to include them in the changes.txt file instead.
12. There is a section near the beginning of the changes.txt file below the total number of cards included where members of our dev team can place brief descriptions of their current projects. A brief sentence or two could provide some interesting info for the user base. This info should be non-technical and "easy to read".

Typical Development Usage

This section details the use of Maven to generate published builds released in the Forge forums.

Team Synchronizing Perspective

(Section incomplete.)

Executing Maven Commands from within Eclipse

Using the included Maven Commands

Once you have the a Forge project imported into Eclipse and have the Maven connectors in place you will notice that the Run -> Run As and the Run -> Debug As menu commands now include the following commands. Some people will only use the Java Application command to test their code and script.

1. Java Applet
2. Java Application
3. JUnit Test (Please do not create JUnit tests. Use TestNG instead. The Other Useful Eclipse Plug-Ins section explains how to install TestNG integration with Eclipse.)
4. Maven build
5. Maven build...
6. Maven clean
7. Maven generate-sources
8. Maven install
9. Maven test

Several example are provided below.

1. The Java Applet menu command is used to run Java Applets. Currently not needed in forge.
2. The Java Application menu command will let you run the forge game. The first time you use this command you may have a java heap space error. Quit forge and then select the Run -> Run Configurations menu command. Select the (x) = Arguments tab and add -Xmx1024m to the VM arguments checkbox.
3. The JUnit Test menu command is used to run JUnit tests. The Run Configurations window can be used to configure this option.
4. The Maven build command will build the forge jar-with-dependencies file in your /git/cardforge/target/ folder. This version of the Maven build command does not open the window labeled Edit Configuration. Use the Maven build... command instead if you want to enter a goal.
5. The Maven build... menu command will give you a window labeled Edit Configuration. You enter the goal into the Goals: text box. Click Apply. Then click Run.
   1. The goal -U -B clean -P osx,windows-linux install will build the jar-with-dependencies file and packages this jar with the necessary files to produce two archives. A windows and unix specific archive and a Mac specific archive. This goal does not upload these archives to a site for distribution.
   2. The goal -U -B clean -P windows-linux install will build a snapshot package build of the Windows/Linux package only.
   3. The goal -U -B clean -P osx install will build a snapshot package build of the Mac OSX package only.
   4. The goal -U -B clean -P osx,windows-linux install release:clean release:prepare release:perform will build the jar-with-dependencies file and packages this jar with the necessary files to produce two archives. A windows and unix specific archive and a Mac specific archive. This goal also uploads these archives to a site for distribution.
   5. The goal -U -B clean install will build the forge jar-with-dependencies file in your /git/cardforge/target/ folder. The Maven install menu command should do the same thing. Full build, package, no uploads. Good for testing.
6. The Maven clean menu command will remove the various files and folders that were added to the target folder as part of the build process. When finished, there will be two empty folders named classes and test-classes located inside of the target folder.
7. The Maven generate-sources command will run the build-helper-maven-plugin. Does not appear to do anything of notice.
8. The Maven install command will build the forge jar-with-dependencies file in your /git/cardforge/target/ folder.
9. The Maven test command will run the TestSuite that is part of the Maven build process. The results can be viewed in Eclipse's Console view.

Releases

Locate your settings.xml file. This file is located inside of a hidden folder named .m2. The .m2 folder should reside inside of your home folder. Open the settings.xml file and enter this data under the servers section. Replace the phrase ThePassword with the correct password:

<servers>
  <server>
    <id>cardforge-site</id>
    <username>releases@cardforge.org</username>
    <password>ThePassword</password>
  </server>
  <server>
    <id>cardforge-repo</id>
    <username>releases@cardforge.org</username>
    <password>ThePassword</password>
  </server>
  <server>
    <id>cardforge-snapshot-repo</id>
    <username>releases@cardforge.org</username>
    <password>ThePassword</password>
  </server>
</servers>

Nightly Builds

There currently is a problem preventing us from executing the Maven goal which executes the Nightly Builds from within Eclipse. The Maven goal needs to be entered from the command line at this time. Mac users can cd to the folder containing their Eclipse project and then execute the Maven goal from the terminal app. The following goal will need the correct password to function:

mvn -U -B clean install site deploy site:deploy -P windows-linux,osx -Dusername=releases@cardforge.org -Dpassword=ThePassword

Once the bug in the FTP upload is solved the following information will allow someone to build and release a Nightly Build from within Eclipse. A Nightly Build will not include the beta release message with support files which is seen on the Forge forum. The beta release message with support files is part of the Bi-Weekly Beta release.

1. Launch Eclipse.
2. Select the Run menu item and then the Run Configurations... item. This will open a dialog named Run Configurations.
3. Select the Maven Build item and click the New button.
4. Select the tab labeled Main.
5. Give this new Maven launch configuration a name such as Build the Nightly builds release.
6. Make sure that the path listed in the Base Directory leads to your local copy of the Forge project.
7. Enter this into the text box labeled Goals: -U -B clean install site deploy site:deploy -P windows-linux,osx -Dusername=releases@cardforge.org -Dpassword=ThePassword.
8. Select the tab labeled JRE.
9. Enter -Xmx1024m into the box labeled VM arguments:.
10. Select the tab labeled Environment.
11. Click the New... button. This will display a dialog named New Environment Variable.
12. Enter MAVEN_OPTS into the box labeled Name:.
13. Enter -Xmx1024m into the box labeled Value:.
14. Click OK.
15. Click the button labeled Apply, the click Run.

You should now be able to execute this Maven launch configuration from the Run -> Run History menu.

Bi-Weekly Betas

There currently is a problem preventing us from executing the Maven goal which executes the Bi-Weekly Beta Releases from within Eclipse. The Maven goal needs to be entered from the command line at this time. Mac users can cd to the folder containing their Eclipse project and then execute the Maven goal from the terminal app. The following goal will need the correct password to function correctly:

mvn -U -B clean -P osx,windows-linux release:clean install site release:prepare release:perform -Dusername=releases@cardforge.org -Dpassword=ThePassword

Once the bug in the FTP upload is solved the following information will allow someone to build and release a Bi-Weekly Beta from within Eclipse.

1. Launch Eclipse.
2. Select the Run menu item and then the Run Configurations... item. This will open a dialog named Run Configurations.
3. Select the Maven launch configuration that you created in the instructions for Nightly Builds which is located underneath Maven Build. Click the Duplicates the currently selected launch configuration button.
4. Select the tab labeled Main.
5. Give this new Maven launch configuration a name such as Build the Bi-Weekly Beta release.
6. Make sure that the path listed in the Base Directory leads to your local copy of the Forge project.
7. Enter this into the text box labeled Goals: -U -B clean -P osx,windows-linux release:clean install site release:prepare release:perform -Dusername=releases@cardforge.org -Dpassword=ThePassword and please note that this text replaces the text that was located in this box.
8. Click the button labeled Apply, the click Run.

You should now be able to execute this Maven launch configuration from the Run -> Run History menu.

Other Useful Eclipse Plug-Ins

These are for Java development.

Troubleshooting

I am getting an error about "invalid LOC header (bad signature)"

This could mean you have a corrupt miglayout jar. Starting at your home folder, try removing the .m2/repository/com/miglayout folder. Then run 'mvn -U clean install' to redownload it. (You may have to install a command-line version of maven to do this.)

I am getting an error about "Fix the build path" or "The type ... cannot be resolved."

1. Right click your Forge project (default name is ForgeSVN [trunk], choose Maven, then Update dependencies. The Update Maven Dependencies window opens.
2. Make sure your Forge project(s) have check marks, then click OK.

I am getting an error about "Exception in thread "main" java.lang.NoClassDefFoundError: forge/view/Main"

You may notice at times a message in Eclipse's console log stating that you need to update your project configuration.

1. Right click your Forge project (default name is ForgeSVN [trunk]), choose Maven, then Update Project Configuration....
2. Make sure your Forge project(s) have check marks, then click OK.

Error on SVN import: "Could not read response body: connection was closed by server"

Discussion here.

Temporary solution: Use multiple command line requests, which will pick up your project where it broke off.

Unfortunately, Subclipse will delete the whole project every time, only to restart and get booted by the server again.

Archived

The Forge team has used several methods of project tracking and distribution in the past. This section stores notes from these adventures. This section also stores non-generic extra pieces of information that are not necessarily helpful to everyone.

These instructions are included only for experimentation only.

Environment Variables (Windows)

You'll often need to modify your system environment variables to develop in Java. How to do it?

1. Click on the Start menu, then the Control Panel.
2. Double click the System icon. If you do not see this icon, you may need to first Switch to Classic View.
3. The System Properties window appears. Click the Advanced tab.
4. Click the Environment Variables button.

Setting Cygwin Variables (Windows)

Cygwin is used by some developers to simulate a Linux environment in Windows.

1. Open the Environment Variables dialog.
2. If you have a variable named HOME in the User variables section, you're already finished.
   • Click Cancel, Cancel to exit.
3. Otherwise, click the New button just underneath the list of User variables. The New User Variable window appears.
4. For the Variable name, type HOME.
5. For the Variable value, type the Windows path to your Cygwin root folder (usually C:/cygwin), followed by /home/ and your Windows user name. For example, C:/cygwin/home/Jordan.
6. Click OK three times in the three different windows that you recently opened.

Batch File Basics (Windows)

If you have a portable environment, a batch file can speed things up considerably by setting variables automatically.

To make a batch file, simply make a new text file and rename the extension to .bat. Right-click the file to edit.

Tips

• When modifying a variable more than once, use !var! to call the variable.
  • This uses the modified (new) value instead of the original (old) value: path=some-folder\bin;!path!

• The current drive letter can be represented by %_d0

Google SVN Repository

Referenced in several threads: http://cardforge.googlecode.com/svn/src/

This repository is very out of date. Please use the repository on slightlymagic.net.