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

Home

Jump to bottom
Katelyn Gadd edited this page Sep 1, 2015 · 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/sq/JSIL.git

Now, let's grab all the submodules:

cd JSIL
git submodule update --init --recursive

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 Visual Studio 2015 (the free Community version works fine). Press F6 to build all projects in the solution. The first build should install NuGet packages for things like gulp and the NUnit test runner. If you see errors regarding the XNA profiles or proxies projects, you can switch to the NoXNA platform to disable them. If you see errors regarding the build for Tests you can feel free to unload those projects; they're largely used for compiler development to ensure bugs aren't introduced.

If any build errors occur outside of XNA or the tests, you should resolve those build failures because JSIL will likely 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# 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# 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 the entry point of that assembly, and pass it your arguments:

    JSIL.InvokeEntryPoint(asm, []);

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/sq/JSIL.git

  3. Run cd JSIL

  4. Run git submodule update --init

Clone this wiki locally