Mercurial > pymonkey

comparison README @ 25:3c2151124cee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Converted pavement.py to manage.py and added a README.
author Atul Varma <varmaa@toolness.com>
date Mon, 29 Jun 2009 10:19:33 -0700
parents
children 9e33fc5a8d92
comparison
equal deleted inserted replaced
24:74b7ad049542 25:3c2151124cee
1 Pymonkey README
2 ---------------
3
4 Pymonkey is a pure Python CAPI module to expose the Mozilla
5 SpiderMonkey engine to Python.
6
7 Rationale and Goals:
8
9 * There's an increasing need for being able to run JS on the server
10 side--particularly untrusted JS. There's Java-based solutions
11 like Rhino out there, but nothing really mature is available for
12 the Python world. Ideally, Pymonkey should enable a Python
13 programmer to create a custom sandboxed environment for executing
14 JS code without needing to write any C.
15
16 * Pymonkey should have awesome Sphinx documentation with doctests
17 and all the trappings of a model Python package. Not only should
18 it be easy for Python programmers to learn how to use the module,
19 but it should also be easy for them to learn more about how
20 SpiderMonkey works by reading the docs and playing around with the
21 code.
22
23 * Pymonkey needs to have outstanding developer ergonomics. Full
24 cross-language stack tracebacks should be available, for instance,
25 and developers should be able to easily debug. Access to memory
26 profiling facilities in JS-land is a must.
27
28 * The module uses the Python CAPI: no SWIG, Pyrex, or other
29 intermediaries. The obvious disadvantage here is that it means
30 more C code, but the advantages are that
31
32 (A) contributors don't need to learn anything other than the
33 Python and SpiderMonkey C APIs to contribute, and
34
35 (B) it means one less dependency, which makes the build process
36 easier.
37
38 The module also doesn't use ctypes because using the SpiderMonkey
39 C API requires fairly complex preprocessor macros defined in the
40 engine's header files.
41
42 Finally, Atul has never really made a straight Python CAPI module
43 before, so he wanted to give it a try.
44
45 Building and Testing
46 --------------------
47
48 Right now building is annoying and difficult because Pymonkey wraps
49 SpiderMonkey 1.8.1, which doesn't yet exist as standalone code--it's
50 only available in the mozilla-central HG repository. As such,
51 Pymonkey currently requires a full build of the Mozilla platform. You
52 can find out how to do this here:
53
54 https://developer.mozilla.org/en/Build_Documentation
55
56 Once you've built Mozilla, you can build the extension and run the
57 tests like this:
58
59 python manage.py build --objdir=PATH_TO_OBJDIR
60
61 Where PATH_TO_OBJDIR is the path to your Mozilla build's objdir (if
62 you don't know what that is, read the build documentation).
63
64 Note that at the moment, the build script is only tested on OS X, and
65 even then some things need to be done to the environment in order for
66 pymonkey to be loaded properly; look at manage.py if you need more
67 specifics on that. Right now this isn't a huge deal because we're only
68 really concerned with the test suite, which is run automatically after
69 building--but obviously it's something that needs to be fixed in the
70 future.
71
72 Example Code
73 ------------
74
75 Right now the only example code that exists is in the test suite at
76 test_pymonkey.py. Check it out and feel free to add more.
77
78 Challenges
79 ----------
80
81 There's a number of challenges that need to be resolved before
82 pymonkey can be really usable. Here's some of them.
83
84 Garbage Collection
85
86 Python's garbage collection uses reference counting, whereas
87 SpiderMonkey's is mark-and-sweep. We'll likely run into situations
88 where there are cycles that exist between SpiderMonkey and Python
89 objects; this is actually quite similar to the relationship between
90 XPCOM and JavaScript in the Mozilla platform--XPCOM uses reference
91 counting too--so detecting such cycles will probably involve creating
92 something akin to XPCOM's cycle collector [1].
93
94 [1] https://developer.mozilla.org/en/Interfacing_with_the_XPCOM_cycle_collector