Build the latest source

Some instructions on how to build the very latest version of FreeGuide. If you have developer access to Git you will want to read the Code Rules. There is also more useful info on the Help us make FreeGuide page.

Windows

Getting git

(Needed for downloading latest source code files for developers.)

You will need a Git client installed. You can use msysGit to install Git for windows, from the following link: install msysGit.

Getting Ant

(Needed to compile to the, unless you use Eclipse)

You will need to download and install the Ant tool. You can download ant from http://ant.apache.org/bindownload.cgi.

(From here on we will be assuming you extracted the downloaded archive to C:\ant)

• Add the C:\ant\bin directory to your PATH environment variable.
• Set the ANT_HOME environment variable to C:\ant\bin.
• You will set up the JAVA_HOME in the next step (Getting the JDK)

Check the Apache documentation on Installing Ant for further details on how to set up the environment variables and path.

You will also need Ant's "optional tasks", which may be distributed under a separate package, possibly called "ant-optional".

Getting the JDK (Java)

In order to compile FreeGuide you will need the Java Developer Kit (JDK), not just the Java Runtime Environment (JRE) version of Java. To get the JDK, got to http://java.sun.com/j2se and follow the link on the right to download J2SE, and then choose to install the JDK. Its easiest to choose the Windows Online Installation, Multi-language version.

Now you will need to set two environment variables: PATH, which should give the location of the "bin" directory inside the directory where you installed the JDK, and JAVA_HOME, which should give the location of the main JDK directory (the one that contains "bin" and other directories). Right-click on My Computer and choose Properties, you will find PATH under Advanced/Environment Variables/System Variables. Find PATH and select edit. The PATHS to the various applications are to be found between semicolons. For example, if your PATH looks like this:

 \system32;C:\Ant\bin

You need to edit it to this, assuming that your JDK is in directory C:\Program Files\Java\jdk1.5.0_06:

 \system32;C:\Ant\bin;C:\Program Files\Java\jdk1.5.0_06\bin

Don't forget to add "\bin" on the end.

You will also need to add a new environment variable, called JAVA_HOME. The value of that should just be the directory in which the JDK is installed, e.g. C:\Program Files\Java\jdk1.5.0_06\bin.

Now, close any DOS/Cmd windows you have opened, and start a new one (to make sure the changes you have made are registered) and type:

 javac

The output should be a long usage message complaining that you haven't provided any source files. If so, you are ready to go - continue to the next section.

If, instead you get something like this:

 'javac' is not recognised as an internal or external command, blah blah blah

or something similar, then you either don't have the JDK installed, or it is not in your PATH. Ask on the FreeGuide developers' mailing list if you need help getting this set up.

Now type:

 echo %JAVA_HOME%

If you get no response, you haven't set up your JAVA_HOME environment variable properly (try logging out and logging in again if you think you have). Ask on our developers' mailing list if you need help here.

Getting the code from Git

To download a full copy of the latest source files from FreeGuide just open DOS command line (cmd), change directory to a suitable directory (e.g. My Documents) and type the following:

 git clone https://codeberg.org/andybalaam/FreeGuide.git

The simplest way to start is just to take the default settings and you will get the latest of everything. Just enter the directory where you want to save the files, preferably something short and simple without long file names, and download.

To get new updates, do this:

 git pull

Below, we assume you checked the source out into a directory called C:\My Documents\freeguide-tv.

Running the classes from the command line

[Note: this is the hard way to do it, but simple. Normally you will want to use an IDE such as Eclipse.]

To build the code, open a DOS or Cmd window and use the "cd" command to change into the directory where you checked out the code:

 cd "C:\My Documents\freeguide-tv"

To compile, type this:

 ant

Run FreeGuide (after building as above) like this:

 ant run

or, alternatively, you can do this:

 cd bin

 java freeguide.startup.Startup

Running using Eclipse

See Using Eclipse in the Linux section.

Linux

Getting the JDK (Java)

In order to compile FreeGuide you will need the Java Developer Kit (JDK), not just the Java Runtime Environment (JRE) version of Java. To get the JDK, got to http://java.sun.com/j2se and follow the link on the right to download J2SE, and then choose to install the JDK.

When you have downloaded and installed the JDK, open a DOS/Cmd window or terminal, and type:

 javac -version

The output should be a long usage message complaining that you haven't provided any source files. Check the very first line of this output (you may need to scroll up). It should be something like "javac 1.5.0_06" - make sure it matches the version you downloaded, not an earlier version. If so, you are ready to go - continue to the next section.

If, instead you get something like this:

 bash: javac: command not found

or something similar, then you either don't have the JDK installed, or it is not in your PATH. Ask on the FreeGuide developers' mailing list if you need help getting this set up.

XMLTV

I really do not recommend installing XMLTV from source - it is very difficult. It is better to use a package for your operating system. On Debian and Ubuntu, this should work:

 apt-get install xmltv

If you do compile from source, ensure you install Tk, so that XMLTV's --gui configuration mode will work from within FreeGuide (i.e. when you click "Choose channels for XMLTV" something will happen).

Getting the code from Git

If git is not installed on your system you will have to install it. On Ubuntu or Debian this should be just:

 sudo apt-get install git-core

To download a full copy of the latest source files from FreeGuide just open a terminal, change directory to a suitable directory (e.g. Documents) and type the following:

Change directory to the Documents directory

 cd Documents

Download the project files using the git command

 git clone https://codeberg.org/andybalaam/FreeGuide.git

To get the latest updates, do this:

 git pull

Now you have two options: you can build on the project from command line, or use Eclipse.

Building on the command line

You will need to install Apache Ant. On Ubuntu or Debian this should be:

 sudo apt-get install ant ant-optional

Change directory to Documents/freeguide-tv.

Build the project by typing:

 ant

and run it with:

 ant run

or:

 cd bin

 java freeguide.startup.Startup

To test a different language translation:

 java -Duser.language=it freeguide.startup.Startup (for italian)

 java -Duser.language=zh -Duser.country=TW freeguide.startup.Startup (for Chinese)

Using Eclipse

• Install Eclipse and launch it
• Create a new project (named e.g. MyFreeGuideProject)

(Note that project source files will be copied from now on to your eclipse MyFreeGuideProject location any modifications you make will affect these files.)

• On the left pane (Package) right-click on the src folder and choose Import.
• Select General>File System, click Next, browse to Documents/freeguide-tv/
• Highlight the src folder, and click ok, eclipse should import all the source files and present them in a tree
• Open the class freeguide.startup.Startup and run it by right-clicking and choosing "Run", then "Run". (To test different language translations, select Run Configurations from the same menu.)
• In the main tab make sure that the Main Class is: freeguide.startup.Startup
• In the Arguments tab, type the following in the VM Arguments field:

 java -Duser.language=it freeguide.startup.Startup

After you've done that, if someone else has made changes and you want to get the latest version, do this:

 cd freeguide-tv

 git pull

Building the jars

Ensure you have ant and ant-optional installed, and do this:

 cd freeguide-tv
 ant jar

Now to run the program do this:

 cd jar
 java -jar FreeGuide.jar

Running the tests

Any code you write should be unit tested, and all the existing unit tests should still pass. You can run the tests like this:

 ant test

or run the "test" target from build.xml in Eclipse's ant plugin.

Please ContactUs if you have questions.