sphinx.addnodesdocument)}( rawsource children]docutils.nodessection)}(hhh](h title)}(hGetting startedh]h TextGetting started}(hhparenthhhsourceNlineNuba
attributes}(ids]classes]names]dupnames]backrefs]utagnamehhhhhhY/home/jac/active/geatec/transcrypt/Transcrypt/transcrypt/docs/sphinx/installation_use.rsthKubh)}(hhh](h)}(hInstallationh]hInstallation}(hh1hh/hhhNhNubah}(h ]h"]h$]h&]h(]uh*hhh,hhhh+hKubh paragraph)}(hX Transcrypt is currently tested under Windows, Linux and OSX, with Chrome, Internet Explorer and Firefox. To be able to use it, Python 3.9 has to be installed. After that, install *virtualenv* as explained in `Jamie Matthews very clear and brief introduction `_. Be sure to install virtualenv for the right Python version, by using the right *pip*. For each Transcrypt project (or group of projects using the same Transcrypt version) create an environment as described in the referenced introduction. To install Trancrypt into that environment, *activate* the environment as also described there, and then type:h](hTranscrypt is currently tested under Windows, Linux and OSX, with Chrome, Internet Explorer and Firefox. To be able to use it, Python 3.9 has to be installed. After that, install }(hTranscrypt is currently tested under Windows, Linux and OSX, with Chrome, Internet Explorer and Firefox. To be able to use it, Python 3.9 has to be installed. After that, install hh?hhhNhNubh emphasis)}(h*virtualenv*h]h
virtualenv}(hhhhJubah}(h ]h"]h$]h&]h(]uh*hHhh?ubh as explained in }(h as explained in hh?hhhNhNubh reference)}(h}`Jamie Matthews very clear and brief introduction `_h]h0Jamie Matthews very clear and brief introduction}(h0Jamie Matthews very clear and brief introductionhh_ubah}(h ]h"]h$]h&]h(]name0Jamie Matthews very clear and brief introductionrefuriGhttps://www.dabapps.com/blog/introduction-to-pip-and-virtualenv-python/uh*h]hh?ubh target)}(hJ h]h}(h ]0jamie-matthews-very-clear-and-brief-introductionah"]h$]0jamie matthews very clear and brief introductionah&]h(]refurihquh*hr
referencedKhh?ubhQ. Be sure to install virtualenv for the right Python version, by using the right }(hQ. Be sure to install virtualenv for the right Python version, by using the right hh?hhhNhNubhI)}(h*pip*h]hpip}(hhhhubah}(h ]h"]h$]h&]h(]uh*hHhh?ubh. For each Transcrypt project (or group of projects using the same Transcrypt version) create an environment as described in the referenced introduction. To install Trancrypt into that environment, }(h. For each Transcrypt project (or group of projects using the same Transcrypt version) create an environment as described in the referenced introduction. To install Trancrypt into that environment, hh?hhhNhNubhI)}(h
*activate*h]hactivate}(hhhhubah}(h ]h"]h$]h&]h(]uh*hHhh?ubh8 the environment as also described there, and then type:}(h8 the environment as also described there, and then type:hh?hhhNhNubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhh,hhubh>)}(h*pip install transcrypt*h]hI)}(hhh]hpip install transcrypt}(hhhhubah}(h ]h"]h$]h&]h(]uh*hHhhubah}(h ]h"]h$]h&]h(]uh*h=hh+hK hh,hhubh>)}(h}from the command prompt. This is the recommended way to install Transcrypt. It is flexible and sets the proper access rights.h]h}from the command prompt. This is the recommended way to install Transcrypt. It is flexible and sets the proper access rights.}(hhhhhhhNhNubah}(h ]h"]h$]h&]h(]uh*h=hh+hKhh,hhubh>)}(hVAlternatively, for manual installation under Windows or Linux, follow the steps below:h]hVAlternatively, for manual installation under Windows or Linux, follow the steps below:}(hhhhhhhNhNubah}(h ]h"]h$]h&]h(]uh*h=hh+hK
hh,hhubh enumerated_list)}(hhh](h list_item)}(h;Download the Transcrypt zip and unpack it anywhere you likeh]h>)}(hhh]h;Download the Transcrypt zip and unpack it anywhere you like}(hhhhubah}(h ]h"]h$]h&]h(]uh*h=hh+hKhhubah}(h ]h"]h$]h&]h(]uh*hhhhhhh+hNubh)}(h=Add *../Transcrypt-/transcrypt* to your system path
h]h>)}(h/transcrypt* to your system pathh](hAdd }(hAdd hj ubhI)}(h$*../Transcrypt-/transcrypt*h]h"../Transcrypt-/transcrypt}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh to your system path}(h to your system pathhj ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhj ubah}(h ]h"]h$]h&]h(]uh*hhhhhhh+hNubeh}(h ]h"]h$]h&]h(]enumtypearabicprefixhsuffix.uh*hhh,hhhh+hKubh>)}(haTo enable minification, additionally the Java Runtime Environment 6 or later has to be installed.h]haTo enable minification, additionally the Java Runtime Environment 6 or later has to be installed.}(hj= hj; hhhNhNubah}(h ]h"]h$]h&]h(]uh*h=hh+hKhh,hhubh note)}(hIf 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 be used side by side selectively.h]h>)}(hjM h](hCIf you install Transcrypt manually, Trancrypt is started by typing }(hCIf you install Transcrypt manually, Trancrypt is started by typing hjO ubhI)}(h*run_transcrypt*h]hrun_transcrypt}(hhhjW ubah}(h ]h"]h$]h&]h(]uh*hHhjO ubh
rather than }(h
rather than hjO ubhI)}(h*transcrypt*h]h
transcrypt}(hhhjj ubah}(h ]h"]h$]h&]h(]uh*hHhjO ubhq. This allows a pip installed Transcrypt and a manually installed Transcrypt to be used side by side selectively.}(hq. This allows a pip installed Transcrypt and a manually installed Transcrypt to be used side by side selectively.hjO ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhjK ubah}(h ]h"]h$]h&]h(]uh*jI hh,hhhh+hNubjJ )}(hIf you also use Numscrypt under Linux or OSX, use the MiniConda installer rather than *virtualenv*, as described in the Numscrypt documentation, since it will allow you to obtain the right version of NumPy.h]h>)}(hj h](hVIf you also use Numscrypt under Linux or OSX, use the MiniConda installer rather than }(hVIf you also use Numscrypt under Linux or OSX, use the MiniConda installer rather than hj ubhI)}(h*virtualenv*h]h
virtualenv}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubhl, as described in the Numscrypt documentation, since it will allow you to obtain the right version of NumPy.}(hl, as described in the Numscrypt documentation, since it will allow you to obtain the right version of NumPy.hj ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhj ubah}(h ]h"]h$]h&]h(]uh*jI hh,hhhh+hNubh>)}(hYou can test your installation as follows (replacing *transcrypt* by *run_transcrypt* if you installed manually rather than with pip):h](h5You can test your installation as follows (replacing }(h5You can test your installation as follows (replacing hj hhhNhNubhI)}(h*transcrypt*h]h
transcrypt}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh by }(h by hj hhhNhNubhI)}(h*run_transcrypt*h]hrun_transcrypt}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh1 if you installed manually rather than with pip):}(h1 if you installed manually rather than with pip):hj hhhNhNubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhh,hhubh)}(hhh](h)}(h[Go to directory *../Transcrypt-/transcrypt/development/automated_tests/transcrypt*h]h>)}(hj h](hGo to directory }(hGo to directory hj ubhI)}(hK*../Transcrypt-/transcrypt/development/automated_tests/transcrypt*h]hI../Transcrypt-/transcrypt/development/automated_tests/transcrypt}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhj ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(hFrom the command prompt run *transcrypt -b -c -da autotest*. This will compile the autotests into a number of .js files and put them into the *__target__* subdirectory. Do NOT go to that directory (there's no need, stay where you went at point 4)h]h>)}(hj h](hFrom the command prompt run }(hFrom the command prompt run hj ubhI)}(h*transcrypt -b -c -da autotest*h]htranscrypt -b -c -da autotest}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubhS. This will compile the autotests into a number of .js files and put them into the }(hS. This will compile the autotests into a number of .js files and put them into the hj ubhI)}(h*__target__*h]h
__target__}(hhhj1 ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh^ subdirectory. Do NOT go to that directory (there’s no need, stay where you went at point 4)}(h\ subdirectory. Do NOT go to that directory (there's no need, stay where you went at point 4)hj ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhj ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(hFrom the command prompt run *transcrypt -r -c autotest*. This will run the autotests with CPython creating file *autotest.html* that refers to the generated *autotest.js* fileh]h>)}(hjR h](hFrom the command prompt run }(hFrom the command prompt run hjT ubhI)}(h*transcrypt -r -c autotest*h]htranscrypt -r -c autotest}(hhhj\ ubah}(h ]h"]h$]h&]h(]uh*hHhjT ubh9. This will run the autotests with CPython creating file }(h9. This will run the autotests with CPython creating file hjT ubhI)}(h*autotest.html*h]h
autotest.html}(hhhjo ubah}(h ]h"]h$]h&]h(]uh*hHhjT ubh that refers to the generated }(h that refers to the generated hjT ubhI)}(h
*autotest.js*h]hautotest.js}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhjT ubh file}(h filehjT ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhjP ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(hXO Start a http server from the command prompt by typing *python -m http.server*, or, dependent on your installation *python3 -m http.server*. In the address bar of your browser, type *localhost:8000/animals.html*. This will load the autotest, run it and compare the output with what was generated by CPython. It should report no errors
h]h>)}(hXN Start a http server from the command prompt by typing *python -m http.server*, or, dependent on your installation *python3 -m http.server*. In the address bar of your browser, type *localhost:8000/animals.html*. This will load the autotest, run it and compare the output with what was generated by CPython. It should report no errorsh](h7Start a http server from the command prompt by typing }(h7Start a http server from the command prompt by typing hj ubhI)}(h*python -m http.server*h]hpython -m http.server}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh%, or, dependent on your installation }(h%, or, dependent on your installation hj ubhI)}(h*python3 -m http.server*h]hpython3 -m http.server}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh+. In the address bar of your browser, type }(h+. In the address bar of your browser, type hj ubhI)}(h*localhost:8000/animals.html*h]hlocalhost:8000/animals.html}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh{. This will load the autotest, run it and compare the output with what was generated by CPython. It should report no errors}(h{. This will load the autotest, run it and compare the output with what was generated by CPython. It should report no errorshj ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hKhj ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubeh}(h ]h"]h$]h&]h(]j6 j7 j8 hj9 j: uh*hhh,hhhh+hKubh>)}(h'To experiment with Transcrypt yourself:h]h'To experiment with Transcrypt yourself:}(hj hj hhhNhNubah}(h ]h"]h$]h&]h(]uh*h=hh+hKhh,hhubh)}(hhh](h)}(h'Create a directory for your experimentsh]h>)}(hj h]h'Create a directory for your experiments}(hj hj ubah}(h ]h"]h$]h&]h(]uh*h=hh+hK!hj
ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(h0Make your own thing there, e.g. *experiment1.py*h]h>)}(hj# h](h Make your own thing there, e.g. }(h Make your own thing there, e.g. hj% ubhI)}(h*experiment1.py*h]hexperiment1.py}(hhhj- ubah}(h ]h"]h$]h&]h(]uh*hHhj% ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK"hj! ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(h(Compile with *transcrypt -b experiment1*h]h>)}(hjI h](h
Compile with }(h
Compile with hjK ubhI)}(h*transcrypt -b experiment1*h]htranscrypt -b experiment1}(hhhjS ubah}(h ]h"]h$]h&]h(]uh*hHhjK ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK#hjG ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(hMake 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 thath]h>)}(hjo h]hMake 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}(hjo hjq ubah}(h ]h"]h$]h&]h(]uh*h=hh+hK$hjm ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(hALoad and run the HTML + JS in the same way as indicated earlier.
h]h>)}(h@Load and run the HTML + JS in the same way as indicated earlier.h]h@Load and run the HTML + JS in the same way as indicated earlier.}(hj hj ubah}(h ]h"]h$]h&]h(]uh*h=hh+hK%hj ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubeh}(h ]h"]h$]h&]h(]j6 j7 j8 hj9 j: uh*hhh,hhhh+hK!ubh>)}(h$You may also want to try the demo's.h]h&You may also want to try the demo’s.}(hj hj hhhNhNubah}(h ]h"]h$]h&]h(]uh*h=hh+hK'hh,hhubh)}(hhh](h)}(h&Installation troubleshooting checklisth]h&Installation troubleshooting checklist}(hj hj hhhNhNubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hK*ubh)}(hhh](h)}(hTranscrypt 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.h]h>)}(hj h](hTranscrypt was installed using }(hTranscrypt was installed using hj ubhI)}(h*pip*h]hpip}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh, but }(h, but hj ubhI)}(h*import transcrypt*h]himport transcrypt}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubhe fails. Transcrypt isn’t a library but a compiler. Install and run it as described in this chapter.}(hc fails. Transcrypt isn't a library but a compiler. Install and run it as described in this chapter.hj ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK,hj ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(hX* 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.h]h>)}(hj h](hX? 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 }(hX; 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 hj ubhI)}(h*java*h]hjava}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh> on the command line. This should give you a list of options: }(h> on the command line. This should give you a list of options: hj ubhI)}(h)*Usage: java [-options] class []args...]*h]h'Usage: java [-options] class []args…]}(hhhj! ubah}(h ]h"]h$]h&]h(]uh*hHhj ubhm and so on. If you can’t or won’t install Java, you can run Transcrypt without minification by using the }(hi and so on. If you can't or won't install Java, you can run Transcrypt without minification by using the hj ubhI)}(h*-n*h]h-n}(hhhj4 ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh command line switch.}(h command line switch.hj ubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK-hj ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubh)}(hX 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.
h]h>)}(hX 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.h]hX 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.}(hjY hjW ubah}(h ]h"]h$]h&]h(]uh*h=hh+hK.hjS ubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hNubeh}(h ]h"]h$]h&]h(]j6 j7 j8 hj9 j: uh*hhj hhhh+hK,ubeh}(h ]&installation-troubleshooting-checklistah"]h$]&installation troubleshooting checklistah&]h(]uh*h
hh,hhhh+hK*ubeh}(h ]installationah"]h$]installationah&]h(]uh*h
hhhhhh+hKubh)}(hhh](h)}(hYour first Transcrypt programh]hYour first Transcrypt program}(hj hj hhhNhNubah}(h ]h"]h$]h&]h(]uh*hhj hhhh+hK1ubh>)}(hX9 Open a command prompt in the *demos/hello* directory and type *transcrypt hello*.
Then start a http server from the command prompt by typing *python -m http.server* or *python3 -m http.server*, dependent on your installation and type *localhost:8000/hello* in the address bar to load the result into your browser.h](hOpen a command prompt in the }(hOpen a command prompt in the hj hhhNhNubhI)}(h
*demos/hello*h]hdemos/hello}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh directory and type }(h directory and type hj hhhNhNubhI)}(h*transcrypt hello*h]htranscrypt hello}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh=.
Then start a http server from the command prompt by typing }(h=.
Then start a http server from the command prompt by typing hj hhhNhNubhI)}(h*python -m http.server*h]hpython -m http.server}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh or }(h or hj hhhNhNubhI)}(h*python3 -m http.server*h]hpython3 -m http.server}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh*, dependent on your installation and type }(h*, dependent on your installation and type hj hhhNhNubhI)}(h*localhost:8000/hello*h]hlocalhost:8000/hello}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubh9 in the address bar to load the result into your browser.}(h9 in the address bar to load the result into your browser.hj hhhNhNubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK3hj hhubh>)}(hAfter 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.h](h;After clicking on both buttons a few times, take a look at }(h;After clicking on both buttons a few times, take a look at hj hhhNhNubhI)}(h*hello.html*h]h
hello.html}(hhhj ubah}(h ]h"]h$]h&]h(]uh*hHhj ubhe.
As you can see, eventhandlers are connected to the buttons exactly as you would do with JavaScript.}(he.
As you can see, eventhandlers are connected to the buttons exactly as you would do with JavaScript.hj hhhNhNubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK6hj hhubh>)}(hThen 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.h](h
Then look at }(h
Then look at hj" hhhNhNubhI)}(h
*hello.py*h]hhello.py}(hhhj+ ubah}(h ]h"]h$]h&]h(]uh*hHhj" ubh.
Note that JavaScript functions like document.getElementById can be called from Python exactly as you would call them from JavaScript, but with Python data.}(h.
Note that JavaScript functions like document.getElementById can be called from Python exactly as you would call them from JavaScript, but with Python data.hj" hhhNhNubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK9hj hhubh>)}(hX The minified JavaScript files *including the Transcrypt runtime* are only around 50kB. 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.h](hThe minified JavaScript files }(hThe minified JavaScript files hjD hhhNhNubhI)}(h"*including the Transcrypt runtime*h]h including the Transcrypt runtime}(hhhjM ubah}(h ]h"]h$]h&]h(]uh*hHhjD ubhX are only around 50kB. 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 }(hX are only around 50kB. 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 hjD hhhNhNubhI)}(h*one*h]hone}(hhhj` ubah}(h ]h"]h$]h&]h(]uh*hHhjD ubh< stateful application, just like it would be on the desktop.}(h< stateful application, just like it would be on the desktop.hjD hhhNhNubeh}(h ]h"]h$]h&]h(]uh*h=hh+hK