Skip to content
This repository has been archived by the owner on Aug 24, 2022. It is now read-only.

Home

Jump to bottom
Kevin Gadd edited this page May 8, 2013 · 31 revisions

This page provides a general overview of using JSILc.

Obtaining Source Code

The first step in running JSIL is to obtain the source code. Since you're on github already, it is assumed that you have a basic understanding of git.

First let's clone the JSIL repo:

git clone https://github.com/kevingadd/JSIL.git

Now, let's grab all the submodules:

cd JSIL
git submodule update --init

You should now have all the source code necessary to be able to run JSIL! Congrats.

Note that, if you ever need to update your local copy of the source code, you can:

git pull --all
git submodule foreach git pull origin master

Building and Running JSIL

Now that you have the source code, open JSIL.sln with Microsoft Visual C# 2010 (Express is fine). Press F6 to build all projects in the solution. Hopefully this will work for you without errors, if you pulled the source code properly. If you see errors regarding the XNA profiles or proxies projects, you can feel free to disable build for those projects, unless you intend to translate XNA games. If you see errors regarding the build for Tests or SmokeTests, you can feel free to disable build for those projects. They are only needed for working on JSIL itself.

If the build succeeded, you should see a message on the bottom left stating so. Also your output window will say something like this:

========== Build: 11 succeeded or up-to-date, 0 failed, 0 skipped ==========

If anything ends up failing, you should resolve those build failures because JSIL will likely not work as intended. Ensure that you built for either Debug x86 or Release x86 (other configurations will not work).

If everything is working as intended, pressing F5 to run JSIL will bring up a command prompt window, send some text through, and then close without an error. Example in output window: (obviously your process ID will likely be different)

The program '[4552] JSILc.vshost.exe: Managed (v4.0.30319)' has exited with code 0 (0x0).

Next step, you can test this with your own C# XNA project. In command prompt, change directory to the path/to/JSIL/bin filepath, and execute this: (replacing path/to/YOUR_FILENAME.exe with your respective compiled C# XNA executable)

JSILc.exe "path/to/YOUR_FILENAME.exe"

You can alternately invoke JSILc with the path to a Visual Studio solution file, and it will attempt to build the solution and translate its output(s):

JSILc.exe "path/to/YOUR_FILENAME.sln"

Assuming nothing errors out, JSILc will load up your assemblies and their dependencies, translate them to javascript, and generate .js files in the current directory. We will use these javascript files to be able to run your program in a web browser.

To control the way JSIL converts your application, or have it convert the assets used by an XNA game, you'll want to create a configuration file - the easiest way is to put a 'YOUR_FILENAME.sln.jsilconfig' next to your sln file so that it is automatically loaded. See the wiki page on configuration files and the wiki page on XNA profiles for more information.

What if you want to test this quickly and rapidly from inside Visual Studio, without command prompt?

Go to Visual Studios; Right Click "Compiler" in the solution explorer, and click Properties. Click the Debug tab. You will see a textbox labelled "Command line arguments". Type in your filepath here (as demonstrated above). Save, and hit F5. JSIL should have ran, using the filepath you just provided as its first argument.

Using the compiled javascript in a webpage

(This section is currently under construction, so consider it an information dump until it is completed and organized.)

For a starting point, use the HTML template in this gist. For more complex use cases, take a look at the various JSIL examples.

Include

<body onload="onLoad()">
  <script type="text/javascript">
    var jsilConfig = {
    };
  </script>
  <script src="../Libraries/JSIL.js" type="text/javascript"></script>

In your page directly in order to get the core JSIL libraries and browser preloader. The 'jsilConfig' variable contains various preferences to configure the preloader. See this page for more information on the preferences available.

The browser preloader uses configurable locations when loading particular types of assets.

  • Assets of type Library (like JSIL.IO, JSIL.XML) are loaded from libraryRoot. These scripts can be non-JSIL javascript and are loaded first to ensure they are available for any JSIL compiled code that depends on them.
  • Assets of type Script are loaded from scriptRoot. These scripts are all loaded before any content is loaded. The manifest(s) generated by JSILc will contain all your compiled code as Script.
  • Assets of type File are loaded from fileRoot. This is best used for raw binary files that your application manipulates using the System.IO and System.File APIs. fileRoot also acts as the root of the virtual file system for your application.
  • Assets of other types are loaded from contentRoot. This is typically used for content for XNA games, and you load the content using an XNA ContentManager. The manifest(s) generated by JSILc will contain all the assets for an XNA game.

If you wish to add additional assets to load (beyond those provided by manifests), you can define a variable named assetsToLoad and put additional asset listings in it to be processed by the browser preloader.

In order to properly get your compiled javascript code to run, you must call your main function in javascript. If you are using the JSIL.Browser preloader, it will automatically call a function named runMain once everything is loaded. The first step is to get a reference to your application's main assembly, like so:

  function runMain () {
    var asm = JSIL.GetAssembly("MyAssemblyName"); // You can use a fully qualified assembly name here if you have it

Next, invoke your main function inside that assembly:

    asm.MyNameSpace.MyProgram.Main([]);

For applications with a synchronous main loop (windows forms and XNA both use one, for example), you may instead wish to create an instance of your application class and start it manually, because it is impossible to have a synchronous main loop in HTML5 - the call to 'Main' will return instantly and might dispose your application class, causing problems. That looks like this:

    var game = new asm.MyNameSpace.Game();
    game.Run();

TO BE CONTINUED

Handling javascript errors (those pesky exceptions!)

JSIL maps .NET exceptions to JavaScript exceptions, so basic JavaScript rules apply:

  • Wrap the call to your program's Main function in a try/catch if you want to manually handle errors that occur there
  • window.onerror can be used as a last-chance handler for any unhandled .NET or JavaScript exceptions (JSIL.Browser installs a basic handler to window.onerror for you that will write errors to the log.)

Additionally, errors that occur inside the JSIL runtime library will often use the JSIL.Host.throwException, JSIL.Host.warning, and JSIL.Host.error functions instead of directly throwing an exception. You can replace these three functions with your own implementations if you wish to customize error handling and warning behavior (by default, warning writes a message to the log, error writes a message to the log and then throws the exception using throwException, and throwException simply throws the exception).

Troubleshooting

If you can't update/grab the submodules follow these steps:

  1. Delete the top folder named JSIL

  2. Run git clone git://github.com/kevingadd/JSIL.git

  3. Run cd JSIL

  4. Run git submodule update --init

Clone this wiki locally