Skip to content

Build Instructions

Jump to bottom
kwood1138 edited this page May 18, 2012 · 9 revisions

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 -c --app --moz-dir=c:\mozilla-src\mozilla-release\obj-xulrunner\dist ..\conf\kylo.conf

In this case, the following two folders would be expected to exist:

C:\mozilla-src\mozilla-release\obj-xulrunner\dist\xulrunner
C:\mozilla-src\mozilla-release\obj-xulrunner\dist\xulrunner-sdk

Configure Your Build

XULRunner applications typically store their settings in a file called application.ini that lives at the root. This is a standard config file format - name value pairs grouped by section, like so:

[Section1]  
parameter1Name=parameter1Value  
parameter2Name=parameter2Value

The build script uses a couple configuration files in the same format to generate the build. Any section/parameters in the build scripts that match runtime settings will override those in the application.ini.

The build configuration files are:
/kylo-browser/tools/build/[platform os]/[platform os].platform.conf /kylo-browser/tools/conf/kylo.conf

Simple documentation is provided within each config file.

*.platform.conf:
This config file stores the locations of various build tools. You'll want to make sure the paths line up to what you have installed.

kylo.conf:
This is the master config file for the Kylo build. The file provided matches settings for the production release of Kylo. If you want to change these values it's best to create a copy of the file. You will be passing this config file to the build script on the command line, so you can name it whatever you like. You can also provide more than one config file at a time.

In addition, the application.ini file is included in the list of config files.

The config files are read in the following order. Each subsequent file will override values of the previous.

*.platform.conf <- application.ini <- kylo.conf [<- *.conf]

Run the Build

To run Kylo builds, you'll be using our custom Python script: build_kylo.py

Simple Build

From the command line:

$ cd [\path\to\kylo-browser]\tools\build  
$ 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.  
[ [Download vcredist_x86.exe](http://www.microsoft.com/en-us/download/details.aspx?id=5555) ]

  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!

This page hosted on the kylo-browser wiki

Copyright 2012 Hillcrest Labs

Clone this wiki locally