This section is aimed at those who want to build calibre2opds from the source code.
There can be many reasons why a user might want to do this. The process has been made as easy as possible so that users can do this without much in the way of spcialist knowledge.
This section of dcoumentation is divided into the following topic areas:
- Development Tool Pre-Requisites
- Setting up the development Environment
- Obtaining the Source Code
- Building calibre2opds
- Running a built calibre2opds
- Building the Installer
Development Tools Pre-Requisites
You need to have downloaded and installed the following pre-requisites before trying to work on Calibre2Opds.
- Java SDK: The Calibre2Opds program is written in the Java programming language. If you want to be able to change and compile Calibre2Opds then you will need the (free) Java Software Development Kit (SDK).
- Subversion This tool is a cross-platform Version Control System. It is used to handle getting Calibre2Opds source into/out of the Google Code system (for releases of Calibre2Opds 2.5 beta 2 or later). There are many implementations of Subversion, but the one we recommend if you are using Windows is the TortoiseSVN release.
Note. If installing the TortoiseSVN version make sure that when installing you select the option to install the command line tools as well.
- Apache Maven: This tool is used to automate the build process. Install according to the instructions on the download page. Select the instructions appropriate to the OS you intend to use.
- lzPack: The Calibre2Opds installer is generated using the lzPack program that can generate cross-platform installation packages. If you are not interested in producing the Calibre2Opds installer then you will not need this package. If you do decide to install this package go for v4.3.4 and do not install version 5.0 which is still in beta and has not been validated for use with calibre2opds development.
- zip: (Windows only). If you want to be able to build the install package then you need a command line version of the zipprogram. If you are not interested in producing the Calibre2Opds installer package then you will not need this program.
The other tool that is commonly used is what is known as an Integrated Development Environment (IDE). This provides a shell that can help with the development tasks and has specialist tools for editing, source control, debugging etc. However whether you use such a tool is your choice although you would almost certainly find it much easier to look at amend the source with the help of an IDE.
There is a wide choice available of IDEs for use with Java. If you already use an IDE that can be used with Java then it is probably best to stick with the one you know. If not, then IDEs for Java that have been found to be good are:
- IntelliJ IDEA This is a powerful Java IDE that is widely used by professional Java developers. This IDE comes in both free and commercial versions. The Free version should be more than sufficient for any calibre2opds development and is the personal favourite of the main calibre2opds developers.
JetBrains have been kind enough to grant us a free open-source development license ; thanks !
- Eclipse Eclipse is an IDE that is widely used and is strongly favored by many Java developers. If you do decide to use Eclipse you will need at the least the Eclipse IDE for Java Developers version although you may go for one of the other versions if you plan to to use Eclipse for more than Java development.
- NetBeans The NetBeans IDE is used by many Java developers. The GUI forms in Calibre2Opds are actually set up using the NetBeans form designer. You should therefore have this installed if you are interested in amending the GUI elements of calibre2Opds, but it is not required for simply amending the main Java code.
Setting up the Development environment
Each of the development tools can require a small amount of tool-specific setup and customizaton of the settings.
Setting up Java
Normally Java is set up by simply running the installer included with the download of the java SDK. However there are some things to check
Make sure that the following Environment variables are set up:
CLASSPATH .;D:\Program Files\Java\jre6\lib\ext\QTJava.zip JAVA_HOME C:\Program Files\Java\jdk1.6.0_19
If you installed to a different location, or were using a different SDK version then the above will need amending accordingly.
The PATH environment variable should contain a reference to %JAVA_HOME%\bin.
Most Linux distributions come with Java Runtime Environment (JRE) pre-installed. However to do Java development you need a Java Development Kit (JDK) installed (which includes the JRE). If your Linux system was built as a development environment then the JDK is probably already installed, but if f that is not the case then simpy download the Java Software Development Kit and install it according to the instructions given on the Java home site.
Setting up Zip (Windows only)
If you want to be able to create the calibre2opds installer package then you need the GNU Zip package installed on your system. The downloaded ZIP installer does not automatically add the relevant entry to the PATH variable to allow the ZIP program to be found from batch files, so you will probably need to do this manually. If you have used the default install location this will involve adding the C:\Program Files\GnuWin32\bin entry to the PATH environment variable.
An alternative is to edit the MakeInstall.cmd file supplied with the calibre2opds source to give a full path to the ZIP program, but this is nowhere near as convenient as adding the directory to the system path.
Setting up Maven
The calibre2Opds project is set up as a Apache Maven project, so you will need to have this installed to be able to build the Calibre2Opds program.
The following Environment variables should be set up
M2_HOME C:\Program files\Maven MAVEN_OPTS -Xms256m -Xmx512m M2 %M2_HOME%\bin
Note that the M2_HOME variable must reflect where you actually installed Maven – the example above assumes the normal default location.
The PATH environment variable should contain a reference to %M2%.
You will need to add the Maven location to your system search path. Linux provides many ways to do this, but probably the easiest and the most generic is to add an entry to do this to the /etc/profile script. If you insstalled maven to /opt/maven then this can be done using entries of the form:
export M2_HOME M2
Apache Maven is installed by default in snow leopard but can be downloaded manually. Instructions can be found here: 
Setting up IntelliJ IDEA
These are notes on setting up the Jetbrains IntelliJ IDEA environment
Obtaining Source Code
Calibre2opds is an open-source product. This means that the source is freely available for any user to download and use.
Source from Launchpad
Launchpad was used for source storage upto (and including) the 2.5 beta 1 release. From 2.5 beta 2 the source repository was moved to googlecode.
Source from Google Code
To get the source code from Google Code you use the Subversion source control system.
The following instructions are based on using the TortoiseSVN package, although they should be easily adaptable to any of the other Subversion implementations that are available:
- Create the folder that is going to be used to hold the calibre2opds source
- Right-Click on the folder and select the SVN Checkout option
- Use the URL https://calibre2opds.googlecode.com/svn/trunk/ to check out the source.
- Once you have the source, you can always right-click the source folder and select the SVN Update option.
TBD: Extra steps required if one want to be able to check in source code changes
Using the Command Line
To simplify the process of compiling calibre2opds from source, some scripts are included to help with automating the Calibre2opds build process. These are make.cmd (for Windows) and make.sh (for Linux/Mac).
If running on other systems then check the files to check what assumptions they have made about the location for the software components. Edit the file (if necessary) to match the setting for your system. They are standard text files so you can both view and edit them with whatever text file editor you have installed on your system. They expect a number of environment variables to have been set up to say where required software components are located. Typical settings might be:
JAVA_HOME=C:\Program Files\Java\jdk1.6.0_29 M2_HOME=C:\Program Files\Maven SVN_HOME=C:\Program Files\TortoiseSVN
although these may be different on your particular system if you have used different install locations. On Windows these are actually set up in the file setenv.cmd and a sample file called setenv.cmd.sample is provided to make it easy to create a setenv.cmd file tailored to your environment. If the environment variables are not set up correctly, then when you run themake.cmd/make.sh file error messages are issued that give appropriate guidance on what to do.
Running these from a Command/Terminal window while located in the Calibre2Opds project folder will run the Calibre2Opds build process. The first time you run them they will download and build a lot of modules associated with Maven and then build Calibre2Opds. Subsequent invocations will only build Calibre2Opds.
There is also the files run.cmd (for Windows) and run.sh (for Linux/Mac) in the Calibre2Opds root folder that can be used on to run the version of calibre2opds that you have just built without the need to build and deploy the install package
Using IntelliJ IDEA
The first time you attempt to use IntelliJ IDEA with calibre2opd there are some settings that you need to set up. These are remembered for subsequent runs so this only needs doing the first time:
- Open the calibre2opds project.
- Specify the Java details
- Inport the Maven settings
Once you ahve done this then you can use the IDEA environment to edit, compile and test calibre2opds without the need to use the command line approach described earlier. Note, however, that if you want to build a deployable calibre2opds package then you still need to follow the command line approach to produce the package.
Running the built Calibre2opds
If you have just built calibre2Opds from source then it is extremely likely that you will want to immediately run the version you have just built. One way is to build the Install package mentioned below and go through the normal install process. How this is inconvenient if you are in the middle of testing and do not want to overwrite the currently installed version of Calibre2Opds.
To help with this batch files are provided that you can run from a command/terminal window while located in the Calibre2Opds source folder. These simply load up the version you have just built:
- Windows: Type in the command
to invoke the run.cmd file that is supplied. This will start calibre2opds using the JAVA command rather than the JAVAW command used when not running in test mode. This will leave a Command window open so that one can see all the messages that are being written to the log file. Possibly more important it will also show any messages that are written to the ‘system console’ that might not make it to the log file.
- Linux/Mac: Type in the command
sh run.sh or ./run.sh
to invoke the run.sh file that is supplied.
if you have any special settings that you want to use then these batch files provide a good starting point for producing your own customized launch files.
The Calibre2Opds install packages are built using the lzPack package. Online documentation is available for lzPack if you want to understand more about how lzPack works, or wish to enhance the Calibre2Opds install package. Additional steps are required for a Mac OSX dmg package as detailed later in this setion
Some scripts are included to help with this:
- Windows: There is the command file MakeInstall.cmd.
- Linux/Mac: There is the script file MakeInstall.sh.
You should check these scripts to see what assumptions they have made about the location for the the lzPack install. Edit them to match the setting for your system.
Simply running these while located in the Calibre2Opds project folder will run the lzPack build process. The following install files are generated:
- calibre2opds.zip: The calibre2opds program files suitable for a manual install
- install.jar: An installer that can be used on systems that support Java such as linux
- install.exe: An installer for use on Windows
- install.app: An installer for use on Mac
All the files that are likely to need amending when producing a new Calibre2Opds release are held at the base of the Calibre2Opds project folder. These files are:
- release.txt: The current release notes. At the very least these should be changed to summarise the amendments made. These are also displayed as the last step in the installation process so anything else that the users need to know for this release can be included here.
- install.xml: This is the control file used by lzPack and it defines the files that are going to be included in the Calibre2Opds install packages. as some of the generated files include the Calibre2Opds version number they will need amending appropriately.
- shortcutSpec.xml: This defines the shortcuts for use on Windows. It will need updating to include the correct binary for the current release.
- Unix_shortcutSpec.xml: This defines the shortcuts for use on Linux. It will need updating to include the correct binary for the current release.
Building the Mac OSX .dmg package
The above steps build the install packages for Windows and Linux, and the platform independent install package. Most Mac OSX users expect applications to be packaged as what is know as a dmg file. This section covers the additional steps that are required to build the dmg package.
Under the covers the dmg file is a archive in a specific format that contains a Mac HFS filing system. It is possible to build the dmg on a none-Mac system using a tool that can handle the dmg file format and HFS filing system. Examples of such applications are:
NOTE: The above Windows packages are not free, so any feedback on equivalents that are free for non-commerical use would be welcomed.
The following is the steps required using the TransMac tool on Windows. Similar steps should work with any other application capable of handling the dmg format.
- Get the skelton dmg file that is included with the calibre2opds source and is available at the location install/calibre2opds.dmg relative to the base of the calibre2opds source tree.
- Mount the calibre2opds.dmg file in TransMac and then open up the dmg file
- Open the calibre2opds.dmg file
- Replace the following files at the root of the dmg file with those from the root of the calibre2opds source tree:
Open up the Calibre2Opds/Contents/Resources/Java folder in the dmg image. Copy to that folder all the files that are located in the calibre2opds source tree at Install\target\dependency. These will be all thw .jar files that are part of calibre2opds. The exact list of files and names may change from those shown in the screenshot to reflect a particular calibre2opds release but you want all of the files present.
- Go back to the Contents folder and open up the info.plist file in a text editor that can handle Macintosh format text files. If you do not have a text editor capable of handling Mac format text files, then the Plist Editor for Windows can be used.
- Change this file so that the details highlighted below are correct. In particular the list of files in the CalassPath array must match those that are actually part of this release of calibre2opds.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd"> <plist version="0.9"> <dict> <key>CFBundleName</key> <string>Calibre2Opds</string> <key>CFBundleIdentifier</key> <string>Gui</string> <key>CFBundleVersion</key> <string>3.0</string> <key>CFBundleAllowMixedLocalizations</key> <string>true</string> <key>CFBundleExecutable</key> <string>JavaApplicationStub</string> <key>CFBundleDevelopmentRegion</key> <string>English</string> <key>CFBundlePackageType</key> <string>APPL</string> <key>CFBundleSignature</key> <string>????</string> <key>CFBundleGetInfoString</key> <string>Calibre2Opds v3.0</string> <key>CFBundleInfoDictionaryVersion</key> <string>6.0</string> <key>CFBundleIconFile</key> <string>icon.icns</string> <key>Java</key> <dict> <key>MainClass</key> <string>Gui</string> <key>JVMVersion</key> <string>1.5+</string> <key>ClassPath</key> <array> <string>$JAVAROOT/OpdsOutput-3.0-SNAPSHOT.jar</string> <string>$JAVAROOT/CalibreQueryLanguage-3.0-SNAPSHOT.jar</string> <string>$JAVAROOT/DataModel-3.0-SNAPSHOT.jar</string> <string>$JAVAROOT/Tools-3.0-SNAPSHOT.jar</string> <string>$JAVAROOT/antlr-2.7.7.jar</string> <string>$JAVAROOT/antlr-runtime-3.1.3.jar</string> <string>$JAVAROOT/jdom-1.1.jar</string> <string>$JAVAROOT/jtidy-r938.jar</string> <string>$JAVAROOT/junit-4.7.jar</string> <string>$JAVAROOT/log4j-1.2.12.jar</string> <string>$JAVAROOT/sqlite-jdbc-184.108.40.206.jar</string> <string>$JAVAROOT/stringtemplate-3.2.jar</string> </array> <key>Properties</key> <dict> <key>apple.laf.useScreenMenuBar</key> <string>true</string> <key>VMOptions</key> <string>-Xms128m -Xmx512m</string> </dict> </dict> </dict> </plist>
You should now have a dmg file that is ready for use on a Mac running OSX.
This section covers hints on using java source-code level debugging in different environments.
Using the Intellij IDEA Java debugger
If you are using the Intellij IDEA Java IDE, the settings for allowing the interactive debugger to be used are as follows:
DebuggRunning in GUI mode
Most users will use calibre2opds in its GUI mode of operation. To enable debugging in this mode the IntelliJ IDEA settings are shown below
You can now run the program in debug mode doing all the things one would expect of a modern interactive debugging evironment. These include:
- Step throught the source code
- Set break points
- Examine variables
It is a good idea to enable assertions when debugging. This includes extra checks that any assumptions in the program execution are not being broken. To do so you need to add eith -ea or -enableassertions to the VM options when running under the IntelliJ debugger.
If you use the run.cmd or run.sh commands located at the root of the calibre2opds source folder then these will pass the relevant options to the Java runtime system.