# Building Kylo from Source

## What You Will Need

REQUIRED

• Python 2.7.3

Our build script is written in Python. The standard process is to run the build script after each testable code change. This will sync your changes from the SRC directory to the build/dist directories.

• XULRunner runtime 12.0

Kylo is built on top of the XULRunner runtime. Many lighter-weight XULRunner applications rely on XULRunner being installed as a separately installed program. Kylo, however, uses a local copy of the runtime. This is more similar to how Firefox is constructed with it's own embedded copy of XULRunner. See the Deploying XULRunner note on developer.mozilla.org for more information. Currently, we run off a patched version of the XULRunner runtime in order to fix a crash bug. Please see the XULRunner note below.

OPTIONAL

• Gecko SDK

The Kylo source code comes with two pre-built XPCOM components - MouseEventTool and SendKeys. If you want to make changes to their source code, you'll need to recompile. Mozilla XPCOM components are built against the Gecko SDK (sometimes called the XULRunner SDK). You'll need to download the Gecko SDK and copy it into the Kylo source tree. Please see the Gecko SDK note below.

Note: The version numbers of the Gecko SDK and XULRunner runtimes need to match! Until the patch is resolved, the supported version number is 12.0

Windows XP/Vista/7 (Please note that only Windows 7 builds have been tested so far)

• Visual C++ Redistributable Package

If you don't plan on modifying C++ components and don't want to compile, you can skip installing the Windows build tools below and just install the redistributable package.

OR

• Visual C++ Express 10.0

• Win7 only: Windows 7 SDK

• CMAKE 2.8.8

If you want to make code changes to the XPCOM components written in C++ (ie. MouseEventTool), you'll need to compile your changes against the Gecko SDK. CMake files are provide if you choose to have the appropriate solution files generated for you.

• Resource Hacker 3.6.0

If you use a custom XULRunner runtime build, or want to change versions, you'll probably want Resource Hacker. Rather than build a custom XULRunner for Kylo, we use Mozilla's recommended method of repurposing the xulrunner-stub.exe file provided in their official releases. This requires the ability to modify the executable - adding the icon asset, changing the name, and adjusting the attached descriptive data. The build script will run Resource Hacker for you to automate this process. Read Mozilla's tips page for more information.

• NSIS 2.4.6

Have this on hand if you want to build an installer. The build script will take care of this process as well.

Mac OS X

• TBD - Sorry, there's still a lot of work to be done here. Using the supplied build script to compile for Mac is not currently supported. This should be resolved shortly...

XULRunner
Currently, Kylo requires a custom build of the XULRunner runtime. This is due to a bug in the "rapid release" versions (I think going back to v5.0). Without this custom release, Kylo will crash when loading Flash, Silverlight, or Quicktime content (possibly other plugins as well). It has to do with some IPC stuff - when Mozilla started allowing plugins to run in separate threads to prevent crashing the whole browser when a plugin died.

The bug details are here

Until that patch gets accepted in their release branch, we'll be hosting the most recent supported XULRunner with our patch on our own servers (XULRunner+Patch). We'll also include the pre-Resource Hacker'ed version of the xulrunner-stub (see below).

You should unzip it under your Kylo source install directory (ie. c:\kylo-browser). At the root of the XULRunner zip file are two directories: build and src. These two directories should be directly under your install directory, like so:

c:\kylo-browser\build
c:\kylo-browser\src


The standard XULRunner directory structure that you'd find in an official Mozilla release is found under src/xulrunner. Like this:

kylo-browser/ (Path to Kylo source install directory)
src/
xulrunner/ <------| Standard XULRunner distributions start here
components/
dictionaries/
*.dll
*.manifest
etc...


If you want to use a standard XULRunner distribution, you can unzip the file into your src directory. That should match the directory structure build_kylo.py expects. You can alternately specify a directory containing xulrunner via the --moz-dir command line option.

Gecko SDK

Note: The Gecko SDK is also called the XULRunner SDK, so you'll see places both on mozilla's servers and our directory structure where the Gecko SDK is located under "xulrunner".

Once you've downloaded the appropriate version of the Gecko SDK, you'll need to put it in a directory where the build process can find it.

Assuming you've grabbed the Windows v10.0.2 release of the SDK, your directory structure should look like this:

kylo-browser/ [Kylo Source Package install location]
src/
xulrunner/  <-------| Already exists from XULRunner runtime install
...
xulrunner-sdk/  <---| Unzip the SDK here
bin/
host/
idl/
include/
lib/
sdk/


The Kylo build script (build_kylo.py) expects that the XULRunner runtime folder (xulrunner) and the Gecko SDK folder (xulrunner-sdk) will be in the same parent folder. By default, the parent folder is src. So if your Kylo source is installed in C:\kylo-browser, then the XULRunner and Gecko folder structure should be like so:

C:\kylo-browser\src\xulrunner
C:\kylo-browser\src\xulrunner-sdk


You may chose to install XULRunner and the Gecko SDK to an external folder. You can then specify this master folder via the build_kylo.py --moz-dir option. So for instance, if you were building XULRunner and the Gecko SDK from source, you might specify something like:

$build_kylo.py ..\conf\kylo.conf  This will use the configuration parameters specified in the ..\conf\kylo.conf file. Without any command line options, the process will use the pre-compiled XPCOM binaries and Kylo app executable from the custom XULRunner runtime package and assemble a "portable" version of Kylo in the build directory. #### Compile C++ Components If you make changes to any of the C++ components, you'll need to recompile. This is done with the -c flag or --compile options. $ build_kylo.py -c ..\conf\kylo.conf


This will recompile ALL components in both the components and extensions directories.

#### Create the App

On Windows, you can chose to create the Kylo.exe executable. This is done by making a copy of the xulrunner-stub.exe file in the XULRunner distribution and modifying the file resources to provide it with the correct name, icon, and metadata. This process is done through Resource Hacker. On OS X, this will create the Kylo.app application package.

$build_kylo.py --app ../conf/kylo.conf  Helpful command line optons: • -v Verbose flag. Prints out all activity to the console • --skip-update Skips the process of copying *.js, *.xul, etc. from src to build • --skip-omni Typically, all application content is compressed into a single archive called omni.ja (formerly omni.jar). You may chose to run with an expanded directory structure. • --app Create the Kylo.app or Kylo.exe file. On Windows, you can skip this process if you have copied the patched version of XULRunner into your source directory. • --c, --compile, --compile-ext, --compile-com Compile C++ components. The first two options compile all components in the extensions and components directories. The second two options compile either the components in the extensions or components directories respectively. • --installer Create the NSIS or DMG installer file in the dist directory. • -R [REVISION NUMBER] Sets the revision number, the fourth number in the program version (ie. build_kylo.py -R 1000 -> 1.0.1.1000). See the note on version numbers below. • ..\conf\Kylo.conf This is the default config file. You can modify this file or create your own. You can also pass in multiple configuration files. To see what all the options do: $ build_kylo.py --help


The standard process is to make your changes to the JS/XUL and then build with the compile, installer, and app options turned OFF. This will recreate the omni.jar package of JS/XUL with your included updates. If you want a hierarchical layout of source instead of the compressed omni package, run build_kylo.py with the --skip-omni option.

Running build_kylo.py without any options and only the configuration file provided will perform the following operations:

1. Create the build and dist directories
2. Sync JS/XUL, components, extensions into the build directory
3. Compress the JS/XUL into the omni.jar (omni.jar/omni.ja is a Mozilla construct - feel free to look this up in developer.mozilla.org

To run a 'complete' build:

$build_kylo.py -c --app --installer -R 1000 ..\conf\kylo.conf  This will perform the following operations: 1. Create the build and dist directories 2. Compile components selected in the [components] directive of the *.conf file 3. Compile components in the extensions selected in the [extensions] directive 4. Sync JS/XUL, components, extensions into the build directory 5. Compress the JS/XUL into the omni.jar 6. "Build" the Kylo executable 7. Run NSIS, create the Kylo installer A Quick Note on Version Numbers The -R/--revision option affects Kylo's version number. The revision number is the fourth number in the full version (ie. 1.0.1.76141). This has previously mapped to an internal revision number matching a Perforce changelist. With the Kylo 1.1.0 release, the revision number is officially optional. For local builds, you can choose to provide a custom value or exclude the -R option. Without specifying a revision number, the version number will only be three parts (ie. 1.1.0). You may be asked to upgrade after running Kylo if the version number is less than the official release. You can ignore this message for development purposes. ## Test Your Build The Kylo build process creates a "portable" package under the build\[OS]\[App Name]\application directory. On standard Windows builds using the default config file, the path looks like this: kylo-browser/ [Kylo Source Package install location] build/ win32/ kylo/ application/ components/ extensions/ xulrunner/ Kylo.exe omni.ja ...  You can run the Kylo.exe file out of this directory. XULRunner apps have a couple flags that might be handy for development purposes. You can append this flags to the Kylo.exe like so: $ cd [path\to\kylo-browser]\build\win32\kylo\application
\$ Kylo.exe -ProfileManager -jsconsole


Options:

• -ProfileManager This will launch a window allowing you to create, delete, and run different profiles. All XULRunner applications (including Firefox) create a profile in the user directory to store preferences and the like. The usefulness of the -ProfileManager option comes in to play when you want to "start fresh" after making some code changes. This lets you delete the current profile, create a new one, and run Kylo again. To do this manually, you would need to delete the user profile directory.

Note: Looks like this feature may finally be on it's way out. Mozilla has an alternate method.

• -jsconsole This will launch the error console along with Kylo. This is useful to see various error messages. Due to the full-screen nature of Kylo, the console window may be hidden. You'll have to alt-tab to move it into view.

For more options, see Mozilla's notes on command line options

Error Messages
You may get the follow error conditions:

1. MSVCR100.dll
After running Kylo.exe, you're immediately presented with a system error stating something like:

The program can't start because MSVCR100.dll is missing from your computer. Try reinstalling the program to fix this problem.

Chances are, you're running the simple build for the first time and did not install Visual C++ Express or the Visual C++ Redistributable Package. If you don't want to compile any C++ components (ie. MouseEventTool), then just install the redistributable.

1. There is a Kylo update available...
After Kylo successfully launches, you may get this message. This is because the update process has run and checked your version number against the latest version available on kylo.tv. To resolve this issue, you can set the version number or revision number so that it is greater than the latest official version.

Kylo version numbers are in the format MAJOR.MINOR.BUILD.REVISION (ie. 1.0.1.76141). With the official 1.1.0 release, the revision number is officially optional. You can adjust the revision number to something like 999999 via the -R option of build_kylo.py. The major, minor and build numbers are set in the application.ini file under src\kylo.

## Success!(?)

After all this, you should have Kylo building and running. If you run into any problems, check out our forum or if it's real bad, submit an issue.

From here, there's lots more you could do...

• Create a new theme
• Build new extensions
• Fix some bugs

Remember to keep an eye on our developer site, TeamKylo blog, wiki and community forums.

Enjoy!