Mercurial > pymonkey

annotate README @ 35:3e66613d1d4d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added information about getting my SpiderMonkey mirror, and also added an option for linking statically to SpiderMonkey's runtime instead of dynamically.
author Atul Varma <varmaa@toolness.com>
date Thu, 02 Jul 2009 15:20:02 -0700
parents 9e33fc5a8d92
children 04a6e9a67ae5
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
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
50 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
51 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
52 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
53
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
54 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
55
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
56 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
57 to build SpiderMonkey.
25
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
58
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
59 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
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 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
62
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
63 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
64 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
65
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
66 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
67
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
68 Example Code
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
69 ------------
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
70
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
71 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
72 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
73
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
74 Challenges
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 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
78 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
79
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
80 Garbage Collection
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 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
83 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
84 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
85 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
86 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
87 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
88 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
89
3c2151124cee Converted pavement.py to manage.py and added a README.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
90 [1] https://developer.mozilla.org/en/Interfacing_with_the_XPCOM_cycle_collector