Setting Up Your Workspace/ru

Most developers spend most of their time procrastinating. One of the favourite ways to procrastinate is to set up your work environment. Perhaps the only benefit to this form of procrastination is that sometimes it can actually lead to an increase in productivity. Some tools are also needed just to get the job done in the first place. This page will take you through some of the things you will need, and other things that are nice to consider when setting up your work environment.

What Options Do You Have, and What Do You Need?

There are many options to choose from when setting up a workspace, however, there are a few key tools that you will need if you want to contribute to the Bukkit Project. Even if you only want to make plugins, there are some tools that will make your job easier, and if you plan to open source, easy for everyone who helps you!

Java

You can't run Java apps without the Java Runtime Environment, and can't compile Java programs without the Java Compiler. We typically build against the Java 6 SDK, so mosey along and find yourself one if you don't yet have it.

Get the Java Development Kit (JDK), it's essential and it includes a copy of the Java Runtime Environment (JRE) if you don't have that already. It is available at : http://www.oracle.com/technetwork/java/javase/downloads/index.html

Get version 1.6 of the JDK. We've not moved to the updated version 1.7 yet.

Note: Bukkit compiles against Java 1.5

Note that if you have a 64 bit operating system, you can choose either 32 bit or 64 bit versions of the JDK. Your development environment will likely have to match the version of the JDK you install. (I know that Eclipse for windows comes in 32 and 64 bit versions and must match the 32 bit or 64 bit version of the JDK. I'm not sure of the other IDEs.)
On windows, you can have both the 32 bit and the 64 bit versions of both the JDK and the JRE installed simultaneously. Firefox, Chrome, Opera, and Safari, and the 32 bit version of IE must use the 32 bit version of the JRE.

Integrated Development Environments

Every programmer has at some point fired up notepad (or their equivalent) and hacked out some code. This is fine if that is what you want to do, however for most of us there are better options available.

An IDE attempts to bring together all the tools you need to develop. More than just a text editor, these software packages can include build tools, sharing frameworks, documentation integration and fancy colours, to name a few. The two main IDEs used to develop with Java are Eclipse and NetBeans. Eclipse is perhaps the more utilised of these two options, but both are very popular in general. If you are starting from scratch, go and get the latest version of Eclipse now, and install it. It's a little hefty, but well worth it to ease development.

We have full instructions for setting up Eclipse. See How_to_Install_Eclipse.

Build Tools

Before we even get the code, there is a tool that the Bukkit Project uses to manage building our code. This is called Maven, and is required if you want to contribute to the Bukkit Project. If you have got Eclipse, there is an excellent plugin called m2eclipse which is accessible through the "Help->Install New Software..." menu item and entering the site address http://m2eclipse.sonatype.org/sites/m2e. If you are experiencing problems installing eclipse plugins due to "missing dependencies" or similar errors, you may need to re-download Eclipse. Many distributions create Eclipse packages that somehow break the ability for eclipse to update and/or install plugins. Downloading Eclipse yourself from the main project page will likely resolve this issue. Also make sure you have installed Maven before trying to build Bukkit, CraftBukkit or any of the other Bukkit projects. Once we have downloaded the code in the next section, we will configure Maven to build it for us.

Getting and Sharing Code

While your brand new IDE is downloading, we can set up a Git. The Bukkit Project manages all its code through the versioning system called Git. Git allows different developers to collaborate on work, tracking all changes that were made and by whom. It is very powerful, and consequently can be a little hard to use sometimes. Finding yourself a good Git tutorial is an excellent idea, however we will go through some of the basics to get you started.

GitHub

GitHub is a code sharing website. If you want to help with Bukkit, or develop plugins, you will need to get a copy of the Bukkit code before you can start. The best option is to set up a GitHub account. You can start that now if you haven't already! With a GitHub account you can share your code with the world, and even if you think you won't need it, its a great thing to have.

Once you have an account, you can get the Bukkit Projects code from our repository, http://github.com/Bukkit.

If you plan to help develop within Bukkit you can 'fork' the project there, or if you plan to just make plugins you can find the Git repository links.

Using Git

You will need to install Git before you can download any source to your personal computer. If you are using Eclipse, Egit is an excellent plugin that handles Git famously. You can find Egit at http://download.eclipse.org/egit/updates.

Once you have Git you can start to use it. A great starting place is the GitHub tutorials. If you are using Egit, there are some excellent tutorials floating around too. The basic idea is as follows.

1. Switch to the Git Repository Exploring Perspective
2. Click the clone existing repository button
3. Enter the details of the remote repository (either your GitHub fork or Bukkits public repository)
4. Clone away!

You can configure different remote repositories. Typically your own GitHub fork would be called origin and the main Bukkit repository would be called upstream. If you are working on a distributed project like Bukkit, it is a good idea to every now and then fetch and merge changes from upstream into your local working copy. This ensures that you have the most recent copy to work on. If you plan to contribute to the Bukkit Project you will need to fork both Bukkit and CraftBukkit, and clone both.

If all you want is to develop plugins, have no fear, you have it simple! You only need to set up one repository and one remote, Bukkit. Your plugin will be a separate project, and for a good example on how you should set it up you can clone the ScrapBukkit code as well.

In order to keep your work separate from updates to the code, you should always work on a separate branch to master, the default. To do this you simply create a new branch of your local copy of master. As you make changes to the code you commit them, and when you have finished with your changes you can merge them back in. There is a lot of etiquette that comes with working on a large project, but if you have gotten this far and intend to contribute to the main project it is worth reading some resources online and asking in the appropriate places (IRC is a good place to come after doing some reading).

Getting Your Code Out There

Sharing of code works both ways - you can download shared code, but you can also share yours with the world. This is a great idea in this open community, as it allows others to help you with your project, or even develop new features for your plugins! If you intend to contribute to the Bukkit Project you must be willing to share your code.

In order to push to your GitHub repository you will need to authenticate yourself. To do this you need an SSH key pair. An SSH can be created within Eclipse or you can use an already existing one if you have it (keep in mind that you will need to make sure eclipse knows where it is if you already have one). In Eclipse, go to Windows->Preferences and typing "SSH" into the search bar. Click on the SSH2 link, and go to "Key Management". If you already have a key, load it now, otherwise create a new one. Once done, copy the public key section, and go to your GitHub account. There is a section where you can paste your public key, and this will be used to authenticate you when you upload code.

If you haven't created a GitHub repository for your code you can do that now, and then push to it from your local repository.

Building the Source Code

You now have all the tools you will need to download, edit and share your code, all that is left is testing it. You should always make sure that your code compiles and works before trying to share it.

In Eclipse, you need to swap back to the Java Perspective. Once there you want to import an existing Maven project into the workspace. To do this go File->Import->Existing Maven Project and follow along. Once you have imported a maven project you can also add team sharing to it, by right clicking the project root and going Team-> add sharing.

Once configured, or if not using m2eclipse, you can clean and install the code. Using m2eclipse, right click the project root, and go Run As->maven clean. If running maven in a console you can use mvn clean. You then use mvn install to build the project.

If working with both Bukkit and CraftBukkit, you must clean install Bukkit first, and then clean install CraftBukkit.

If you decided to clone ScrapBukkit to see how it works, clean install it after the other two.

Where To From Here

There is lots more involved in actually developing and testing your code, however hopefully you now have the tools to get started. If you find any particularly useful tutorials make sure to link them here!

It is suggested that you start with Programming A Plugin.