Developer Guide

From VuzeWiki
Jump to: navigation, search

Welcome to the Vuze Developer Guide! This page will provide assistance to developers that are new to Vuze and give an explanation on what they will be working with. The guide will be based upon Vuze v4.5.1.0 and will be making use of Eclipse v3.5 (Galileo) as the software used to build the project on. The software in this guide will be run on the Linux Operating System.

This page will be a very basic introduction to Developing Vuze, so feel free to make any useful contributions and/or correct any errors.

Getting Started[edit]

By this point you should have successfully built your Vuze project on a software development environment (Recommended using Eclipse). If you have not yet done this, then Using Eclipse will help. Once your project has been built, you should see the following:

Alternative text

Don't worry about the warnings you may have as shown in the image above. These do not stop the software from running successfully. You should also see the list of directories shown on the left under the Package Explorer tab. These contain the different files that may be edited.

There are a few files located within the project, so this makes it difficult to try and identify which is the main class. The main class is located in the following directory:

  • azureus2/src/azureus/ui/

You should see a comment at the top of the page declaring: "This is the main of all mains!"

This is how the main class should look:

Alternative text

As you can probably see from the comments in this class, the sole purpose of it at the moment is to call upon the other main class located at:

  • azureus2/src/org/gudy/azureus2/ui/swt/

Navigating through Vuze[edit]

As you have probably already seen, the built project shows a huge amount of different directories and hundreds of class files. As this is difficult for a new developer to navigate, this part of the guide which give a description on each of the folders and how the files relate to each other.

  • Note: Make sure you read comments before you start editing code. As well as summarising what the code does, it may also tell you not to change the code featured in the file in anyway.

The three directories below contain the majority of the .java files that you will mainly be using to access the source code.

  • azureus3/src
  • azureus2/src
  • uis/src

You can find more information on these directories at Understanding the Source Code.

The rest of the directories contain different files that do not relate to the source code and thus you may not need to edit.

  • JRE System Library contains several .jar folders. You will not need to edit this part of the project at all.
  • Referenced Libraries should have a list of .jar folders that you will have imported when building your project. If you are not sure what these are, Using Eclipse will detail which .jar folders should have been imported.
  • azureus2 has a child directory lib which contains four .jar folders and a file called JavaApplicationStub. Again these .jar folders do not need to be edited and JavaApplicationStub just shows encrypted text.
    • The directories libOSXAccess and libWIN32Access contain loads of different file types, some of which are encoded. A common file type found within these directories are .cpp. These are c++ files. Again however, these files should not need to be edited at all.
  • azureus3 also has a child directory lib. However this in turn contains nothing.
  • build has several files with many different file types.
    • First you will see a .xml file and two .txt files. ChangeLog.txt contains a description of updates and bug fixes made with each new version of Vuze. GPL.txt is the General Public Licence. Refer to this before making any changes to your project.
    • You can find many different image files such as .png or .gif located at build/com/aelitis/azureus and also build/org/gudy/azureus2/ui/icons.
    • By searching through build/org.bouncycastle, you will find some more directories containing package.html These files however comprise of nothing more than just some text.
    • If you look in build/org/gudy/azureus2/platform/unix, you will find a startupScript. This is the part of code that performs the start up. As the comment at the top of the page suggests, you should not alter this part of the code.
    • You can find some release notes at build/org/pf/release-notes. Like ChangeLog.txt, these files comprise of updates and bug fixes and gives the specific changes that have been made.
  • dist is an empty directory.
  • docs has three .tmpl that you will not need to consider in your project.
  • src is also an empty directory.
  • test has several .java files that run tests for the software. You can find the main test class at test/src/org/gudy/azureus2/ui/swt/test.
  • uis contains 3 .jar folders, which again, you should not need to edit.
  • build.xml is a .xml file that will build you project. It should return "BUILD SUCCESSFUL" after a few minutes.

Understanding the Source Code[edit]

This part of the guide will go into detail about the three source code folders:

  • azureus3/src
  • azureus2/src
  • uis/src

For azureus3/src you will find most of the .java files located at azureus3/src/com.aelitis.azureus. Here you will be presented with four directories. The directory ui contains mainly images and skins, and a folder named swt (see bottom of section.)

azureus2/src has a similar structure to azureus3/src. A lot of the directory names are indistinguishable between the two source code files. However, they do contain different .java files, so don't let this fool you. Again you will find some directories named ui which more or less consistently contain files that relate to the GUI.

uis/src is a much smaller directory. You will find some more release notes at uis/src/org/pf as well as some more .java files. The majority of the .java files can be found at uis/src/org/gudy.azureus2/ui.

  • Note: The ui folder located in this directory is not similar to the ui folders found at azureus3/src and azureus2/src. Here it does not have any image files or anything related to the GUI, but comprises of entirely .java files.

In these folders you will find some directories named swt. This refers to the Standard Widget Toolkit. The .java files you will find in here will relate to the GUI such as skins, toolbars etc.

  • Note: This section could be greatly expanded. If you have a good understanding of the three source code directories mentioned above, then feel free to contribute.

Helpful Tips[edit]

If you browse through these directories, you can see that there are hundreds of files. This part of the guide will give you some tips to help you navigate through the code.

If you explore these different .java files, you can jump to different parts of the code, such as methods, objects, classes etc. The following example is located at the following directory:

  • azureus3/src/org.apache.commons.lang/

Alternative text

As you can see, by expanding the file, we can see the Entities class located within. By double clicking the class name, Eclipse jumps to the part of the code where the public class Entities is written.

Further more, by exploring deeper into the Entities class, we can jump to the different methods located within the code, and even find the variables that are located inside these methods as seen here:

Alternative text

By taking some time navigating through these directories, you will soon become familiar with what the different .java files are, what they do and how they relate to each other.

If you come across a piece of code that implements an interface, you can highlight the interface name and it will indicate the location of that file.

Alternative text

The image above tells us that you can find the interface TorrentDownloaderCallBackInterface at:

  • azureus2/src/org/gudy/azureus2/core3/torrentdownloader.

Highlighting parts of the code will also reveal other details such as comments, parameters, author, etc.