...

Installing NetBeans

NetBeans 7.0 1 (or latest version) is recommended for both performance and features (plus, >7.1 includes Git support out-of-the-box). Download it from http://www.netbeans.org/.

...

If you are running on Linux/Unix, you will need to make the downloaded script executable (e.g. {{chmod \+x netbeans-\[version\]-full-linux.sh}}).

Subversion Client

Subversion support is already included in NetBeans. However, it requires that the command line client is installed and available on your local machine.

• For most Linux distributions, you should be able to just install the Subversion client available in your distribution's repositories.

• For Windows, there is now a 'Bundled Subversion Client for Windows' Plugin which you can install from within NetBeans
  • Go to Tools -> Plugins to install the plugin.

• For Windows/RedHat/Solaris, CollabNet also offers free Subversion downloads that are specifically tested with NetBeans: http://www.collab.net/downloads/netbeans/ (Free to download, but they require that you register first. Registration is also free, but requires a valid email address)

Install Maven Support

Integrate an External Installation of Maven

Although not required, it is recommended to install an external version of Apache Maven. This will ensure that you are using a version of Maven which DSpace supports. (You should check the latest pre-requisites if you are using a later version of DSpace) However, if the Bundled version of Maven is a supported version, you are welcome to use it.

If you wish to integrate an external install of Maven:

• First, install Maven:
  • For most Linux distributions, you should be able to just install the Maven client available in your distribution's repositories.
  • For all other operating systems, you can install the latest version from the Apache Maven site.
• Configure Netbeans to use your external Maven:
  • Go to the "Tools" menu, and select "Options" (on OS/X, this is "NetBeans" -> "Preferences")
  • Select the "Miscellaneous" section.
  • Select the "Maven" tab.
  • Modify the "Maven Home" field. It's possible that Netbeans will already see your external version of Maven (if it's in your PATH). However, if it says that it is using the "Bundled" Maven, then you'll want to fill out the "Maven Home" field with the location of your external installation of Maven.
  • In the middle of this page, you may also need to fill out the location of your "Local Repository". This should be the location of the ".m2" directory under your user's home directory.
    • On Linux and OS/X, it should be located at ~/.m2/
    • On Windows, it should be located at C:\Documents and Settings\username\.m2 (Windows XP) or C:\Users\username\.m2 (Windows 7)
  • All the other Maven settings should be fine as their defaults. Press "OK" to save your changes.

Checkout DSpace from Subversion

NetBeans makes the checkout and configure process easy, as it does nearly everything for you.

• Under the 'Team' menu, go to 'Checkout'. Enter the URL for the DSpace Subversion repository: https://scm.dspace.org/svn/repo/dspace, and click on the next button.
• Next to 'Repository Folder(s)', click on 'Browse', and browse to the version of DSpace you wish to checkout. A few hints:
  • Stable, tested versions of DSpace are available under tags (e.g. tags/dspace-1_7_1)
  • Latest Bug Fixes (though slightly less stable) are available under branches (e.g. branches/dspace-1_7_x)
  • Unstable code is available on trunk. It is not recommended that you checkout trunk unless you are a Committer & know what you are doing!
• Choose a local folder to checkout to (or leave the default entry), and leave the 'Scan for NetBeans projects after Checkout' option selected, and click on 'Finish'.
• When NetBeans completes the checkout, it will pop-up a dialog telling you that it found projects during the checkout. Choose 'Open Project' from the dialog. Select all the projects that you wish to open (hold down ctrl to select multiple), and click the OK button.

...

Git Plugin / Support

As long as you are running NetBeans 7.1 or above, Git support comes pre-installed in NetBeans.

However, if you are running NetBeans 7.0, you can install the "Git" plugin by going to "Tools -> Plugins" and finding the plugin named "Git" under the list of "Available Plugins".

If you plan to also occasionally run Git commands from your command-line, you may wish to install Git on your operating system:

• Git Homepage (includes info on downloading & installing on major platforms)

Maven Support

As long as you are on a recent version of NetBeans (> 6.7), Maven support is included out-of-the-box.

Integrate an External Installation of Maven

Although not required, it is recommended to install an external version of Apache Maven. This will ensure that you are using a version of Maven which DSpace supports. (You should check the latest pre-requisites if you are using a later version of DSpace) However, if the version of Maven that is bundled with NetBeans is a supported version, you are welcome to use it.

If you wish to integrate an external install of Maven:

• First, install Maven:
  • For most Linux distributions, you should be able to just install the Maven client available in your distribution's repositories.
  • For all other operating systems, you can install the latest version from the Apache Maven site.
• Configure Netbeans to use your external Maven:
  • Go to the "Tools" menu, and select "Options" (on OS/X, this is "NetBeans" -> "Preferences")
  • Select the "Miscellaneous" section.
  • Select the "Maven" tab.
  • Modify the "Maven Home" field. It's possible that Netbeans will already see your external version of Maven (if it's in your PATH). However, if it says that it is using the "Bundled" Maven, then you'll want to fill out the "Maven Home" field with the location of your external installation of Maven.
  • In the middle of this page, you may also need to fill out the location of your "Local Repository". This should be the location of the ".m2" directory under your user's home directory.
    • On Linux and OS/X, it should be located at ~/.m2/
    • On Windows, it should be located at C:\Documents and Settings\username\.m2 (Windows XP) or C:\Users\username\.m2 (Windows 7)
  • All the other Maven settings should be fine as their defaults. Press "OK" to save your changes.

Checkout DSpace from GitHub

NetBeans makes the checkout and configure process easy, as it does nearly everything for you.

• Wiki Markup

  Under the '_Team_' menu, go to '_Git_' -> '_Clone_'. (In Git terminology, "clone" just means you are downloading an exact copy of the remote code repository to your local machine.) Enter the URL for the DSpace Repository in GitHub which you wish to work with (e.g. [https://github.com/DSpace/DSpace.git] OR if you have your own fork: https://github.com/\[your-username\]/DSpace.git), optionally enter in a GitHub username/password, and click on the "Next" button.

  • Wiki Markup

    _*IMPORTANT NOTE:*_ If you plan to do a larger amount of DSpace development or local changes, you may wish to first ["fork"|http://help.github.com/fork-a-repo/] the DSpace GitHub Repository (https://github.com/DSpace/DSpace) to your own GitHub account. This will create your own copy of the DSpace source code under your GitHub account (e.g. https://github.com/\[your-username\]/DSpace). You can then checkout your own forked repository to work from and commit local changes to (push changes to). For more information, see the GitHub help page on ["Forking a Repo"|http://help.github.com/fork-a-repo/].

• Next, select the "Remote Branch" you wish to develop on. A few hints:
  • Branches named "dspace-#_#_x" (e.g. dspace-1_8_x) are Bug Fix / Maintenance branches. So, the latest code in that bug-fix or maintenance release will be available on that branch. This code tends to be more stable overall. As such, we recommend most developers use the appropriate Bug Fix / Maintenance branch for their local development.
  • The branch named master is roughly equivalent to the old SVN Trunk. As such, it may not be as stable, but it includes the latest & greatest code which is being prepared for the next major release. Unless you know what you are doing, we do NOT recommend running this code in Production. It is essentially "unsupported" until it is officially released.
  • If you wish to work from a "tagged" (official release) version of DSpace (e.g. 1.8.2), you can download those releases as Tarballs/Zips from: https://github.com/DSpace/DSpace/tags^{Image Added} You could then use that Tarball/Zip to import it into your own Git/GitHub or SVN repository as you see fit.
• Next, choose a local parent folder to use and the "Clone Name" (actual folder name for the source code), and leave the 'Scan for NetBeans projects after Clone' option selected, and click on 'Finish'. (All other options you should be able to leave as their default values.)
• When NetBeans completes the clone, it will pop-up a dialog telling you that it found a number of DSpace projects (Maven projects) during the checkout. Choose 'Open Project' from the dialog. Select all the projects (and/or subprojects) that you wish to open (hold down ctrl or shift to select multiple), and click the "Open" button. (Don't worry you can always Open or Close projects later if you notice you opened up too few or too many)

After the clone has completed, you'll notice NetBeans considers each DSpace Maven "module" to be a separate project. So, you'll see separate projects for "DSpace XML-UI" and "DSpace JSP-UI", even though these are all cloned from the same source code.

Git/GitHub Hints & Tips

The following are a few hints/tips which you may want to utilize to ease your development processes with NetBeans and GitHub:

1. Fork your own Repo to store your local changes: As recommended above, you really should think about forking your own copy of the DSpace GitHub repository. As GitHub describes in their "Fork a Repo" guide, forking lets you create your own personal copy of the codebase. It not only provides you a place to put your local customizations. It also provides an easier way to contribute your work back to the DSpace community (via a GitHub Pull Request).
2. For easier Fetch/Merge, setup an "upstream" repository location: This is only really relevant if you have your own personal "fork" (see #1). If you have forked the DSpace GitHub repository, then you may want to setup an "upstream" remote that points at the central DSpace GitHub repository. This is described in more detail in the GitHub "Fork a Repo" guide. Perform the following:

   • Wiki Markup
     On the command-line, change directory to your local machines' cloned DSpace git repository, which is also your DSpace source directory (e.g. {{cd \[dspace-src\]}})

   • Run the following 'git' command from that directory:

     Code Block
     git remote add upstream git://github.com/DSpace/DSpace.git

     (Technically you can name it something other than "upstream". But, "upstream" is just the GitHub recommended naming convention).
   • For more information about how this comes in handy, see the section below on "#Fetch & Merge Example via NetBeans".

Fetch & Merge Example via NetBeans

1. Fetch changes from DSpace Main GitHub: You fetch (and later merge) changes that have occurred in the central DSpace GitHub Repository:
   • From NetBeans: Right-click on the "DSpace Parent Project" (root project) and then select: "Git" -> "Remote" -> "Fetch". This will pop up a window that will allow you to easily select the "upstream" configured repository to fetch the latest changes from, and allow you to choose the "master" branch to apply them to. Once you click "Finish", a new "upstream/master" branch will be created locally with the latest changes to be merged.

   • Wiki Markup
     From Command-line in your DSpace source directory (e.g. {{cd \[dspace-src\]}}: {{git fetch upstream}}

2. Merge changes into your Local Git Repo: Remember, "fetching" changes just brings them into your local-machine's copy of the Git repository. You'll then need to merge those changes with yours and push the changes back to your personal public GitHub repository.
   • From NetBeans: Right-click on the "DSpace Parent Project" (root project) and then select: "Git" -> "Merge Revision". This will pop up a window to let you select which "branch" to merge into your currently checked out code. If press "Select", you'll see a new branch called "upstream/master" under "Branches -> Remote". Selecting that branch will merge the latest code from "upstream/master" into whatever branch you currently are working with (e.g. "master").
   • From Command-line in that same directory: git merge upstream/master
3. Quick Status of Local Git Repo: If you want to see what happened, you can look at the "Status" information:
   • From NetBeans: Right-click on the "DSpace Parent Project" (root project) and then select: "Git" -> "Show History". Click the "Search" button (without entering any search info). It will bring back results that will show you where the HEAD pointer is (latest commit in your local machine's git repo) versus where the 'origin/master' is (latest commit in your personal GitHub repo).
   • From Command-line in that same directory: git status (will tell you how many "commits ahead" of 'origin/master' you now are)
4. Push Merged Code up to your Personal GitHub Repo: Finally, assuming all went well, you can push your changes back up to GitHub into your public personal repository:
   • From NetBeans: Right-click on the "DSpace Parent Project" (root project) and then select: "Git" -> "Remote" -> "Push". This will pop up a window that will allow you to select the "origin" repository (your personal fork in GitHub), and allow you to choose the "master" branch to push to.
   • From Command-line in that same directory: git push origin master

Build DSpace from NetBeans

...