Getting started
===============

Installation
------------

Transcrypt is currently tested under Windows and Linux, OS X will probably follow later. To be able to use it, Python 3.5 has to be installed. To install Transcrypt itself, make sure the Scripts directory of your Python installation is in your system path.
Then type

*pip install transcrypt*

from the command prompt. This is the recommended way to install Transcrypt.

Alternatively, for manual installation under Windows or Linux, follow the steps below:

1.	Download the Transcrypt zip and unpack it anywhere you like
2.	Add *../Transcrypt-<version>/Transcrypt to your system path*

N.B. If you install Transcrypt manually, Trancrypt is started by typing *run_transcrypt* rather than *transcrypt*. This allows a pip installed Transcrypt and a manually installed Transcrypt to by used side by side selectively.

You can test your installation as follows (replacing *transcrypt* by *run_transcrypt* if you installed manually rather than with pip):

1.	Go to directory *../Transcrypt-<version>/transcrypt/development/automated_tests/transcrypt*
2.	From the command prompt run *transcrypt -b autotest.py*. This will compile the autotests into file *autotest.js* and put it into the *__javascript__* subdirectory. Do NOT go to that directory (there's no need, stay where you went at point 4)
3.	From the command prompt run *transcrypt -r autotest.py*. This will run the autotests with CPython creating file *autotest.html* that refers to the generated *autotest.js* file
4.	Load the autotest.html into your browser, e.g. by clicking on it (tests were done with Chrome). It will load *autotest.js*, run it and compare the output with what was generated by CPython. It should report no errors

To experiment with Transcrypt yourself:

1.	Create a directory for your experiments
2.	Make your own thing there, e.g. *experiment1.py*
3.	Compile with *transcrypt -b experiment1.py*
4.	Make an HTML page that will load your code in the browser. Use the HTML file generated by the autotest as an example of how to do that
5.	Load and run the HTML + JS

You may also want to try the demo's.

Troubleshooting checklist
~~~~~~~~~~~~~~~~~~~~~~~~~

1. Transcrypt was installed using *pip*, but *import transcrypt* fails. Transcrypt isn't a library but a compiler. Install and run it as described in this chapter.
2. Transcrypt reports an error containing the word 'java'. Transcrypt produces both prettyfied and minified JavaScript output. For the minification it makes use of the Google Closure Compiler, which is included in the distribution and requires Java to run. You can check proper installation of Java by typing the word *java* on the command line. This should give you a list of options: *Usage: java [-options] class []args...]* and so on. If you can't or won't install Java, you can run Transcrypt without minification by using the *-n* command line switch.
3. The static checker doesn't find all errors it could. The static checks, performed by the PyFlakes package that's part of the distribution, are of a 'light' variety. Style checks and false positives are avoided. The accent is on finding undefined identifiers and unused variables.

Your first Transcrypt program
-----------------------------

Open a command prompt in the *demos/hello* directory and type *transcrypt hello.py*.
Then click on *hello.html* to load it into your browser.

After clicking on both buttons a few times, take a look at *hello.html*.
As you can see, eventhandlers are connected to the buttons exactly as you would do with JavaScript.

Then look at *hello.py*.
Note that JavaScript functions like document.getElementById can be called from Python exactly as you would call them from JavaScript, but with Python data.

The minified JavaScript file *including the Transcrypt runtime* is only 10kB. With non-trivial programs this overhead becomes negligible. Transcrypt applications in themselves don't need any external files. Of course you can use extensive JavaScript libraries served by content delivery networks as you normally would. But you can also make very compact stand alone applications. The most efficient thing to do is pack all functionality for a page in a single Transcrypt program. Note that the source can consist of many modules if needed and many callback entrypoints can be provided. But it is *one* stateful application, just like it would be on the desktop.

.. literalinclude:: ../../demos/hello/hello.html
	:tab-width: 4
	:caption: In hello.html, Python handlers are attached directly to the onclick events
	
.. literalinclude:: ../../demos/hello/hello.py
	:tab-width: 4
	:caption: In hello.py, JavaScript function document.getElementById is called directly from Python, using plain Python values
	
.. _command_line_switches:
	
Command line switches
---------------------
The available command line switches will be shown if you run transcript -h.
They are specified in the source code of Transcrypt as follows:

.. literalinclude:: ../../modules/org/transcrypt/utils.py
	:pyobject: CommandArgs
	:tab-width: 4
	:caption: Transcrypt command line switches as specified in module/orgs/transcrypt/utils.py
	
If static checking is enabled, insert dummy definitions of global JavaScript variables between :ref:`__pragma__ ('skip') and __pragma__ ('noskip') <skipping_fragments>` to prevent needless complaints of the checker. The static checks are geared towards avoiding false alarms, and mainly check undefined names and unused variables. Style checks are deliberately avoided.

Compiling for node.js
---------------------

Transcrypt will allow you to target *node.js* while writing your server code in Python.
This opens up the exploding world of node.js libraries from your favorite programming language.
In the *demo/nodejs_demo* subdirectory of the installation, you'll find the following trivial example of a node.js server app:

.. literalinclude:: ../../demos/nodejs_demo/nodejs_demo.py
	:tab-width: 4
	:caption: Using node.js from Transcrypt is trivial, including the use of 'require' to tap into a vast set of libraries
	
Follow the steps below to run this demo:

- Install node.js from *https://nodejs.org*
- Open a node.js command prompt
- Go to the *demo/nodejs_demo* directory
- Compile the demo with *transcrypt -b -p. nodejs_demo.py* (note the dot after the p switch)
- Go to *demo/nodejs_demo/__javascript__* directory
- Type *node nodejs_demo.js* (or *node nodejs_demo.min.js* if you want to run the minified version)
- In your browser, view the result at *http://localhost:8080*
- Repeatedly reload the page to see the text change (Google Chrome may actually reload twice)
