-
Notifications
You must be signed in to change notification settings - Fork 240
Home
This page provides a general overview of using JSILc.
- For information on how to configure JSILc, see Configuration Files and jsilConfig.
- For information on the XNA Content Project support, see XNA Profiles.
- See Meta Attributes for information on how to customize the code JSILc generates for you.
- See Projects Using JSIL for more examples of working JSIL-based app and game ports.
- Not a .NET developer, or looking for tips on hand-tuning JavaScript performance? See JavaScript Performance For Madmen
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
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.
(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
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).
If you can't update/grab the submodules follow these steps:
-
Delete the top folder named JSIL
-
Run git clone git://github.com/sq/JSIL.git
-
Run cd JSIL
-
Run git submodule update --init