Mercurial > pymonkey

annotate README @ 26:9e33fc5a8d92

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added a link to ServerJS.
author Atul Varma <varmaa@toolness.com>
date Mon, 29 Jun 2009 10:35:06 -0700
parents 3c2151124cee
children 3e66613d1d4d
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
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
9 * There's an increasing need for being able to run JS on the server
26
9e33fc5a8d92 Added a link to ServerJS.
Atul Varma <varmaa@toolness.com>
parents: 25
diff changeset
10 side--particularly untrusted JS [1]. There's Java-based solutions
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
11 like Rhino out there, but nothing really mature is available for
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
12 the Python world. Ideally, Pymonkey should enable a Python
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
13 programmer to create a custom sandboxed environment for executing
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
14 JS code without needing to write any C.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
15
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
16 * Pymonkey should have awesome Sphinx documentation with doctests
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
17 and all the trappings of a model Python package. Not only should
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
18 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
19 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
20 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
21 code.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
22
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
23 * 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
24 cross-language stack tracebacks should be available, for instance,
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
25 and developers should be able to easily debug. Access to memory
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
26 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
27
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
28 * 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
29 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
30 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
31
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
32 (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
33 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
34
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
35 (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
36 easier.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
37
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
38 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
39 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
40 engine's header files.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
41
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
42 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
43 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
44
26
9e33fc5a8d92 Added a link to ServerJS.
Atul Varma <varmaa@toolness.com>
parents: 25
diff changeset
45 [1] https://wiki.mozilla.org/ServerJS
9e33fc5a8d92 Added a link to ServerJS.
Atul Varma <varmaa@toolness.com>
parents: 25
diff changeset
46
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
47 Building and Testing
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
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
50 Right now building is annoying and difficult because Pymonkey wraps
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
51 SpiderMonkey 1.8.1, which doesn't yet exist as standalone code--it's
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
52 only available in the mozilla-central HG repository. As such,
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
53 Pymonkey currently requires a full build of the Mozilla platform. You
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
54 can find out how to do this here:
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
55
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
56 https://developer.mozilla.org/en/Build_Documentation
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
57
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
58 Once you've built Mozilla, you can build the extension and run the
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
59 tests like this:
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
60
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
61 python manage.py build --objdir=PATH_TO_OBJDIR
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
62
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
63 Where PATH_TO_OBJDIR is the path to your Mozilla build's objdir (if
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
64 you don't know what that is, read the build documentation).
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
65
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
66 Note that at the moment, the build script is only tested on OS X, and
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
67 even then some things need to be done to the environment in order for
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
68 pymonkey to be loaded properly; look at manage.py if you need more
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
69 specifics on that. Right now this isn't a huge deal because we're only
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
70 really concerned with the test suite, which is run automatically after
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
71 building--but obviously it's something that needs to be fixed in the
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
72 future.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
73
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
74 Example Code
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
75 ------------
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
76
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
77 Right now the only example code that exists is in the test suite at
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
78 test_pymonkey.py. Check it out and feel free to add more.
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
79
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
80 Challenges
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
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
83 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
84 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
85
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
86 Garbage Collection
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 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
89 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
90 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
91 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
92 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
93 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
94 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
95
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
96 [1] https://developer.mozilla.org/en/Interfacing_with_the_XPCOM_cycle_collector