Mercurial > pymonkey

annotate README @ 36:04a6e9a67ae5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added a bit to the README.
author Atul Varma <varmaa@toolness.com>
date Thu, 02 Jul 2009 15:29:07 -0700
parents 3e66613d1d4d
children 7401af070bb8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
1 Pymonkey README
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
2 ---------------
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
3
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
4 Pymonkey is a pure Python CAPI module to expose the Mozilla
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
5 SpiderMonkey engine to Python.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
6
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
7 Rationale and Goals:
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
8
36
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
9 * Python and JS are fairly complementary languages. Python provides
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
10 tremendous developer productivity via its dynamic language
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
11 features, its vibrant library of third-party client-side code, and
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
12 its ease of readability. JavaScript, on the other hand, is widely
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
13 known by a vast number of casual programmers due to its
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
14 availability in web browsers; it was also envisioned from its
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
15 conception to be executed as untrusted code, which gives it a lot
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
16 of security features that Python has always lacked.
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
17
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
18 * There's an increasing need for being able to run JS on the server
36
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
19 side--particularly untrusted JS [1]. For instance, being able to
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
20 duplicate business logic on the server and client (i.e., browser)
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
21 would be very useful. There's Java-based solutions like Rhino out
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
22 there, but nothing really mature is available for the Python
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
23 world. Ideally, Pymonkey should enable a Python programmer to
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
24 create a custom sandboxed environment for executing JS code
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
25 without needing to write any C.
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
26
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
27 * Pymonkey should have awesome Sphinx documentation with doctests
36
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
28 and all the trappings of a model Python package. Not only should
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
29 it be easy for Python programmers to learn how to use the module,
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
30 but it should also be easy for them to learn more about how
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
31 SpiderMonkey works by reading the docs and playing around with the
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
32 code.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
33
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
34 * Pymonkey needs to have outstanding developer ergonomics. Full
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
35 cross-language stack tracebacks should be available, for instance,
36
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
36 and developers should be able to easily debug. Access to memory
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
37 profiling facilities in JS-land is a must.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
38
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
39 * The module uses the Python CAPI: no SWIG, Pyrex, or other
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
40 intermediaries. The obvious disadvantage here is that it means
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
41 more C code, but the advantages are that
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
42
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
43 (A) contributors don't need to learn anything other than the
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
44 Python and SpiderMonkey C APIs to contribute, and
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
45
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
46 (B) it means one less dependency, which makes the build process
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
47 easier.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
48
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
49 The module also doesn't use ctypes because using the SpiderMonkey
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
50 C API requires fairly complex preprocessor macros defined in the
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
51 engine's header files.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
52
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
53 Finally, Atul has never really made a straight Python CAPI module
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
54 before, so he wanted to give it a try.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
55
26
9e33fc5a8d92 Added a link to ServerJS.
Atul Varma <varmaa@toolness.com>
parents: 25
diff changeset
56 [1] https://wiki.mozilla.org/ServerJS
9e33fc5a8d92 Added a link to ServerJS.
Atul Varma <varmaa@toolness.com>
parents: 25
diff changeset
57
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
58 Building and Testing
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
59 --------------------
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
60
35
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
61 You can either build SpiderMonkey off the mozilla-central HG
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
62 repository, or off a mirror I made of its SpiderMonkey directory. The
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
63 latter can be obtained here:
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
64
35
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
65 http://hg.toolness.com/spidermonkey/
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
66
35
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
67 Just HG clone that repository and read the instructions in the README
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
68 to build SpiderMonkey.
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
69
35
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
70 Then come back to the root of your pymonkey repository and run:
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
71
35
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
72 python manage.py build --static --objdir=PATH_TO_OBJDIR
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
73
35
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
74 Where PATH_TO_OBJDIR is the path to your Mozilla/SpiderMonkey build's
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
75 objdir.
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
76
3e66613d1d4d Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
Atul Varma <varmaa@toolness.com>
parents: 26
diff changeset
77 Note that at the moment, the build script is only tested on OS X.
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
78
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
79 Example Code
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
80 ------------
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
81
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
82 Right now the only example code that exists is in the test suite at
36
04a6e9a67ae5 Added a bit to the README.
Atul Varma <varmaa@toolness.com>
parents: 35
diff changeset
83 test_pymonkey.py. Check it out and feel free to add more.
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
84
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
85 Challenges
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
86 ----------
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
87
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
88 There's a number of challenges that need to be resolved before
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
89 pymonkey can be really usable. Here's some of them.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
90
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
91 Garbage Collection
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
92
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
93 Python's garbage collection uses reference counting, whereas
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
94 SpiderMonkey's is mark-and-sweep. We'll likely run into situations
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
95 where there are cycles that exist between SpiderMonkey and Python
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
96 objects; this is actually quite similar to the relationship between
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
97 XPCOM and JavaScript in the Mozilla platform--XPCOM uses reference
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
98 counting too--so detecting such cycles will probably involve creating
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
99 something akin to XPCOM's cycle collector [1].
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
100
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
101 [1] https://developer.mozilla.org/en/Interfacing_with_the_XPCOM_cycle_collector