-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathDeveloping.html
More file actions
141 lines (137 loc) · 10.4 KB
/
Copy pathDeveloping.html
File metadata and controls
141 lines (137 loc) · 10.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="en" lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Pyjs</title>
<link rel="stylesheet" type="text/css" media="screen" href="assets/main.css"/>
</head>
<body>
<div id="menu">
<div id="logo"><a href="./" title="Pyjs!"><img src="assets/images/pyjs.128x128.png" alt="Pyjs Logo" /></a></div>
<ul class="simple">
<li class="section">About</li>
<li><a class="reference external" href="About.html">About</a></li>
<li><a class="reference external" href="Overview.html">Overview</a></li>
<li><a class="reference external" href="Translator.html">Translator</a></li>
<li><a class="reference external" href="Download.html">Download</a></li>
<li><a class="reference external" href="GettingHelp.html">Getting Help</a></li>
<li class="section">Documentation</li>
<li><a class="reference external" href="examples">Examples</a></li>
<li><a class="reference external" href="UIHierarchy.html">UI Hierarchy</a></li>
<li><a class="reference external" href="api">API Docs</a></li>
<li><a class="reference external" href="book/Bookreader.html">Book</a></li>
<li><a class="reference external" href="https://github.com/pyjs/pyjs/wiki">Wiki</a></li>
<li class="section">Development</li>
<li><a class="reference external" href="Developing.html">Develop</a></li>
<li><a class="reference external" href="Optimize.html">Optimize</a></li>
<li><a class="reference external" href="Contribute.html">Contribute</a></li>
<li><a class="reference external" href="Roadmap.html">Roadmap</a></li>
</ul>
</div>
<div id="body">
<h1 class="title">Develop</h1>
<div class="section" id="source-code">
<h1>Source Code</h1>
<p>The pyjs repositories are hosted <a class="reference external" href="https://github.com/pyjs">on Github</a>. For read-only access to pyjs' main repository use the following:</p>
<pre class="literal-block">
git clone https://github.com/pyjs/pyjs.git
</pre>
<p>If you want to add contributions to the project source code see <a class="reference external" href="Contribute.html">Contribute</a> for details.</p>
</div>
<div class="section" id="how-to-set-up-a-web-development-environment">
<h1>How to set up a Web development environment</h1>
<p>Web application development can be tricky: it can come as a bit of a shock when compared to Python app development to learn that web browsers do not come with <strong>any</strong> proper debugging assistance whatsoever, by default. You <em>will</em> need to install and/or enable a debugger in the browsers that you use:</p>
<ul class="simple">
<li>For Firefox, install both <a class="reference external" href="https://addons.mozilla.org/de/firefox/addon/javascript-debugger/">Venkman</a> and <a class="reference external" href="https://addons.mozilla.org/de/firefox/addon/firebug/">Firebug</a>.</li>
<li>For IE, install the <a class="reference external" href="http://www.microsoft.com/downloads/en/details.aspx?FamilyID=2f465be0-94fd-4569-b3c4-dffdf19ccd99&amp;DisplayLang=en">Microsoft Script Debugger</a>.</li>
<li>For Safari, go to the settings and enable "Development".</li>
<li>For Chrome, <a class="reference external" href="http://chrispederick.com/work/web-developer/">Web Developer</a> has been reported to make your life easier. (Problems with Chrome/Chromium? See <a class="reference external" href="https://github.com/pyjs/pyjs/wiki/googlechromeproblems">main Wiki</a>)</li>
<li>Opera has stack tracing by default.</li>
</ul>
<p>For debug output using pyjs' <tt class="docutils literal">logging</tt> module is recommended (see below for details).</p>
<p>You should also note that the pyjs compiler has a <tt class="docutils literal"><span class="pre">-d</span></tt> option which will enable a Python-like stack trace when a JavaScript exception occurs. The amount of JavaScript generated can be FIVE times larger, so only enable this during development.</p>
<p>Lastly, it is worth reiterating that pyjs Desktop runs as pure Python: you should give serious consideration to running the application under pyjs Desktop alongside developing it for the browser. The availability of Python runtime stack traces and the simple fact that the standard Python interpreter is much better at catching certain kinds of errors than (brain-damaged) browsers has generally found to make life much much easier.</p>
</div>
<div class="section" id="debug-output">
<h1>Debug Output</h1>
<p>With pyjs you can use full Python-style logging (Python's flexible <a class="reference external" href="http://docs.python.org/library/logging.html">event logging module</a> has been ported to pyjs). Additional handlers allow you to display log messages in a dedicated <em>div</em> element in the HTML document, in the Web browser's error console, and with JavaScript's alert() function.</p>
<pre class="literal-block">
from pyjamas import logging
log = logging.getConsoleLogger() # other loggers: Alert, Append, Print ...
...
log.error("Hello, here is an %s error", err_name)
</pre>
<p>For a good understanding of the logging module read the <a class="reference external" href="http://docs.python.org/howto/logging.html">Python Logging HOWTO</a>; most of it directly applies to pyjs. Additional loggers provided by pyjs, and how you'd use them:</p>
<ol class="arabic simple">
<li>AlertLogger: <tt class="docutils literal">log = logging.getAlertLogger()</tt> shows a browser alert popup dialog for each log message.</li>
<li>AppendLogger: <tt class="docutils literal">log = logging.getAppendLogger()</tt> appends text to the end of the HTML document body. The <em>div</em> element holding the log messages can be accessed by its element ID ('logging_<loggername>', which defaults to 'logging_pyjs') for styling.</li>
<li>ConsoleLogger: <tt class="docutils literal">log = logging.getConsoleLogger()</tt> passes log messages on to the error console of Firebug/Chrome/Opera/<a class="reference external" href="http://msdn.microsoft.com/en-us/library/dd565625(v=vs.85).aspx">IE8+</a> using the <a class="reference external" href="http://getfirebug.com/logging">console logging</a> functions.</li>
<li>PrintLogger: <tt class="docutils literal">log = logging.getPrintLogger()</tt> prints text to <em>cerr</em>, the default error output stream. This is a good choice when developing/testing with pyjs Desktop.</li>
<li>NullLogger: <tt class="docutils literal">log = logging.getNullLogger()</tt> disable logging completely and safely.</li>
</ol>
<div class="section" id="enable-additional-debug-information-in-javascript">
<h2>Enable additional debug information in JavaScript</h2>
<p><tt class="docutils literal">pyjsbuild</tt> command line switch <tt class="docutils literal"><span class="pre">-d</span></tt>, <tt class="docutils literal"><span class="pre">--enable-debug</span></tt> generates a vast amount of extra information for every single line of code in JavaScript. This blows up your code size drastically, use it as the last resort.</p>
</div>
</div>
<div class="section" id="building-user-interfaces-with-pyjs">
<h1>Building User Interfaces with pyjs</h1>
<p>To become familiar with the user interface side of pyjs, you might like to refer to the <a class="reference external" href="examples">examples</a> online and also compile and run them locally.</p>
<p>You might find the <a class="reference external" href="UIHierarchy.html">ui module class hierarchy</a> useful. The <tt class="docutils literal">ui</tt> module contains all of the
main classes you need to create your user interface. At first, this module can be a quite confusing because of the number of classes defined. However, there is <a class="reference external" href="api">API documentation</a>, along with a <a class="reference external" href="ControlsTutorial.html">tutorial</a> on how to create your own interactive widget.</p>
<p>You might also have a look at the <a class="reference external" href="https://developers.google.com/web-toolkit/doc/latest/DevGuide">GWT Documentation</a> for widgets that have been ported to pyjs.</p>
</div>
<div class="section" id="sources-overview">
<h1>Sources Overview</h1>
<p>The pyjs repo contains both shared libraries (usable in Python or JavaScript mode), and "runners" that execute the code (Python or JavaScript) on a particular engine. Here is a quick what-is-what.</p>
<dl class="docutils">
<dt>/addons/</dt>
<dd>Contributed libraries, added to the pythonpath when translating code to js</dd>
<dt>/bin/</dt>
<dd>Executables created when bootstrapping appear here</dd>
<dt>/builder/</dt>
<dd>Boilerplate files etc. for <tt class="docutils literal">pyjs_build</tt>'s building process</dd>
<dt>/contrib/</dt>
<dd>Miscellaneous helper scripts</dd>
<dt>/doc/</dt>
<dd>Documentation, tutorials, and scripts that build them</dd>
<dt>/examples/</dt>
<dd>Lots of examples with their build scripts (also used to test all is ok)</dd>
<dt>/examples/libtest/</dt>
<dd>Used for unit-testing, build it and launch it to have in-browser tests performed</dd>
<dt>/library/</dt>
<dd>All common widgets and utilities, with platform overides when necessary</dd>
<dt>/library/gwt/</dt>
<dd>libs tracking original gwt sources, without improvements</dd>
<dt>/library/pyjamas/</dt>
<dd>libs mirroring and cross-linking gwt/ ones, to add pyjs-specific features</dd>
<dt>/pgen/</dt>
<dd>Python parsing suite recoded in python</dd>
<dt>/pygtkweb/</dt>
<dd>Just ignore that for now</dd>
<dt>/pyjd/</dt>
<dd>Desktop runner (executes non-translated code, on several possible backends)</dd>
<dt>/pyjs/</dt>
<dd>Actual python-to-js tools: translator, browser linker, python builtins and stdlib recoded for javascript</dd>
<dt>/pysm/</dt>
<dd>Spidermonkey runner (executes js code on that js engine)</dd>
<dt>/pyv8/</dt>
<dd>Google V8 runner (executes js code on that js engine)</dd>
<dt>/bootstrap.py</dt>
<dd>The script through which everything starts</dd>
<dt>/test.py</dt>
<dd>Very useful to easily launch unit-tests (especially libtest) on several engines</dd>
</dl>
<p>Key points to remember:</p>
<ul class="simple">
<li>the "/pyjs" part is only used in translated mode, other libraries
are used both for translated (browser, pyv8, pysm...) and non-translated (pyjd) modes</li>
<li>each widget is split between "/library/pyjamas/ui/" and
"/library/gwt/ui/" trees, to differenciate legacy and pyjs-added features</li>
<li>for testing, "/test.py" and compiled "/examples/libtest" are your best allies</li>
</ul>
</div>
</div>
</body>
</html>