[pypy-svn] r44604 - pypy/dist/pypy/doc

[antocuni at codespeak.net]

Author: antocuni
Date: Thu Jun 28 17:10:17 2007
New Revision: 44604

Added:
   pypy/dist/pypy/doc/carbonpython.txt   (contents, props changed)
Log:
some docs about carbonpython



Added: pypy/dist/pypy/doc/carbonpython.txt
==============================================================================
--- (empty file)
+++ pypy/dist/pypy/doc/carbonpython.txt	Thu Jun 28 17:10:17 2007
@@ -0,0 +1,230 @@
+==================================================
+CarbonPython, aka C# considered harmful
+==================================================
+
+CarbonPython overview
+=====================
+
+CarbonPython is an experimental RPython to .NET compiler. Its main
+focus is to produce DLLs to be used by other .NET programs, not
+standalone executables; if you want to compile an RPython standalone
+program, have a look to `translate.py`_.
+
+Compiled RPython programs are much faster (up to 250x) than
+interpreted IronPython programs, hence it might be a convenient
+replacement for C# when more speed is needed. RPython programs can be
+as fast as C# programs.
+
+RPython is a restrict subset of Python, static enough to be analyzed
+and compiled efficiently to lower level languages.  To read more about
+the RPython limitations read the `RPython description`_.
+
+**Disclaimer**: RPython is a much less convenient language than Python
+to program with. If you do not need speed, there is no reason to look
+at RPython.
+
+**Big disclaimer**: CarbonPython is still in a pre-alpha stage: it's
+not meant to be used for production code, and the API might change in
+the future. Despite this, it might be useful in some situations and
+you are encouraged to try it by yourself. Suggestions, bug-reports and
+even better patches are welcome.
+
+.. _`RPython description`: coding-guide.html#restricted-python
+.. _`translate.py`: faq.html#how-do-i-compile-my-own-interpreters
+
+
+Quick start
+===========
+
+Suppose you want to write a little DLL in RPython and call its
+function from C#.
+
+Here is the file mylibrary.py::
+
+    from pypy.translator.cli.carbonpython import export
+
+    @export(int, int)
+    def add(x, y):
+        return x+y
+
+    @export(int, int)
+    def sub(x, y):
+        return x-y
+
+
+And here the C# program main.cs::
+
+    using System;
+    public class CarbonPythonTest
+    {
+        public static void Main()
+        {
+            Console.WriteLine(mylibrary.add(40, 2));
+            Console.WriteLine(mylibrary.sub(44, 2));
+        }
+    }
+
+Once the files have been created, you can compile ``mylibrary.py``
+with CarbonPython to get the corresponding DLL::
+
+    $ python carbonpython.py mylibrary.py
+    ... lot of stuff
+
+Then, we compile main.cs into an executable, being sure to add a
+reference to the newly created ``mylibrary.dll``::
+
+    # with mono on linux
+    $ gmcs /r:mylibrary.dll main.cs
+
+    # with Microsoft CLR on windows
+    c:\> csc /r:mylibrary main.cs
+
+Now we can run the executable to see whether the answers are right::
+
+    $ mono main.exe
+    42
+    42
+
+
+Multiple entry-points
+=====================
+
+In RPython, the type of each variable is inferred by the `Annotator`_:
+the annotator analyzed the whole program top-down starting from an
+entry-point, i.e. a function whose we specified the types of the
+parameters.
+
+This approach works for a standalone executables, but not for a
+library that by definition is composed by more than one
+entry-point. Thus, you need to explicitly specify which functions you
+want to include in your DLL, together with the expected input types.
+
+To mark a function as an entry-point, you use the ``@export``
+decorator, which is defined in ``pypy.translator.cli.carbonpython``,
+as shown by the previous example.  Note that you do not need to
+specify the return type, because it is automatically inferenced by the
+annotator.
+
+.. _`Annotator`: dynamic-language-translation.html#annotator
+
+
+Namespaces
+==========
+
+Since `CLS`_ (Common Language Specification) does not support module
+level static methods, RPython functions marked as entry-points are
+compiled to static methods of a class, in order to be accessible by
+every CLS-compliant language such as C# or VB.NET.
+
+The class which each function is placed in depends on its
+**namespace**; for example, if the namespace of a function ``foo`` is
+``A.B.C``, the function will be rendered as a static method of the
+``C`` class inside the ``A.B`` namespace. This allows C# and
+IronPython code to call the function using the intuitive ``A.B.C.foo``
+syntax.
+
+By default, the default namespace for exported function is the same as
+the name of the module. Thus in the previous example the default
+namespace is ``mylibrary`` and the functions are placed inside the
+corresponding class in the global namespace.
+
+You can change the default namespace by setting the ``_namespace_``
+variable in the module you are compiling::
+
+    _namespace_ = 'Foo.Bar'
+
+    @export(int, int)
+    def f(x, y):
+        pass
+
+Finally, you can also set a specific namespace on a per-function
+basis, using the appropriate keyword argument of the ``@export``
+decorator::
+
+    @export(int, int, namespace='Foo.Bar')
+    def f(x, y):
+        pass
+
+
+.. _`CLS`: http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-335.pdf
+
+
+Exporting classes
+=================
+
+RPython libraries can also export classes: to export a class, add the
+``@export`` decorator to its ``__init__`` method; similarly, you can
+also export any methods of the class::
+
+    class MyClass:
+
+        @export(int)
+        def __init__(self, x):
+            self.x = x
+
+        @export
+        def getx(self):
+            return self.x
+
+
+Note that the type of ``self`` must not be speficied: it will
+automatically assumed to be ``MyClass``.
+
+The ``__init__`` method is not automatically mapped to the .NET
+constructor; to properly initialize an RPython object from C# or
+IronPython code you need to explicitly call ``__init__``; for example,
+in C#::
+
+    MyClass obj = new MyClass();
+    obj.__init__(x);
+
+Note that this is needed only when calling RPython code from the
+outside; the RPython compiler automatically calls ``__init__``
+whenever an RPython class is instantiated.
+
+In the future this discrepacy will be fixed and the ``__init__``
+method will be automatically mapped to the constructor.
+
+
+Accessing .NET libraries
+========================
+
+**Warning**: the API for accessing .NET classes from RPython is highly
+experimental and will probably change in the future.
+
+In RPython you can access native .NET classes through the ``CLR``
+object defined in ``translator.cli.dotnet``: from there, you can
+navigate through namespaces using the usual dot notation; for example,
+``CLR.System.Collections.ArrayList`` refers to the ``ArrayList`` class
+in the ``System.Collections`` namespace.
+
+To instantiate a .NET class, simply call it::
+
+    ArrayList = CLR.System.Collections.ArrayList
+    def foo():
+        obj = ArrayList()
+        obj.Add(42)
+        return obj
+
+At the moment there is no special syntax support for indexers and
+properties: for example, you can't access ArrayList's elements using
+the square bracked notation, but you have to call the call the
+``get_Item`` and ``set_Item`` methods; similarly, to access a property
+``XXX`` you need to call ``get_XXX`` and ``set_XXX``::
+
+    def foo():
+        obj = ArrayList()
+        obj.Add(42)
+        print obj.get_Item(0)
+        print obj.get_Count()
+
+Static methods and are also supported, as well as overloadings::
+
+    Math = CLR.System.Math
+    def foo():
+        print Math.Abs(-42)
+        print Math.Abs(-42.0)
+
+
+At the moment, it is not possible to reference assemblies other than
+mscorlib. This will be fixed soon.