git.iko.soy/Idris-dev
on master help sign in
Merge pull request #3422 from jfdm/codegens-docs
0d3d2d6Jan de Muijnck-Hughes
docs/reference/codegen.rstnew file+123
compare with master
unifiedsplit
@@ -0,0 +1,123 @@
1+************************
2+Code Generation Targets
3+************************
4+
5+``Idris`` has been designed such that the compiler can generate code for
6+different backends upon request. By default ``Idris`` generates a ``C``
7+backend when generating an executable. Included within the standard Idris installation are backends for Javascript and Node.js.
8+
9+However, there are third-party code generators out there. Below we
10+describe some of these backends and how you can use them when
11+compiling your ``Idris`` code. If you want to write your own codegen for your language there is a `stub project on GitHub <https://github.com/idris-lang/idris-emptycg>`__ that can help point you in the right direction.
12+
13+Official Backends
14+==================
15+
16+C Language
17+----------
18+
19+Javascript
20+----------
21+
22+To generate code that is tailored for running in the browser
23+issue the following command:
24+
25+::
26+
27+ $ idris --codegen javascript hello.idr -o hello.js
28+
29+
30+Generating code for NodeJS is slightly different. Idris outputs a
31+JavaScript file that can be directly executed via node.
32+
33+::
34+
35+ $ idris --codegen node hello.idr -o hello
36+ $ ./hello
37+ Hello world
38+
39+
40+Idris can produce very big chunks of JavaScript code (hello world
41+weighs in at 1500 lines). However, the generated code can be minified
42+using the `closure-compiler
43+<https://developers.google.com/closure/compiler/>`__ from Google.
44+
45+::
46+
47+ java -jar compiler.jar --compilation_level ADVANCED_OPTIMIZATIONS --js hello.js
48+
49+
50+Node.js
51+-------
52+
53+
54+Third Party
55+============
56+
57+.. note::
58+
59+ These are third-party code generations and may have bit-rotted or
60+ do not work with current versions of Idris. Please speak to the
61+ maintainors of the generators if there are any problems.
62+
63+Python
64+------
65+
66+`Available online <https://github.com/ziman/idris-py>`__:
67+
68+Java
69+----
70+
71+
72+
73+`Available online <https://github.com/idris-hackers/idris-java>`__:
74+
75+
76+``idris hello.idr --codegen java -o hello.jar``
77+
78+Note: The resulting .jar is automatically prefixed by a header including
79+an .sh script to allow executing it directly.
80+
81+PHP
82+---
83+
84+`Available online <https://github.com/edwinb/idris-php>`__
85+
86+LLVM
87+-----
88+
89+
90+`Available online <https://github.com/idris-hackers/idris-llvm>`__:
91+
92+CIL (.NET, Mono, Unity)
93+-----------------------
94+
95+::
96+
97+ idris --codegen cil Main.idr -o HelloWorld.exe \
98+ && mono HelloWorld.exe
99+
100+The resulting assemblies can also be used with .NET or Unity.
101+
102+Requires `idris-cil <https://github.com/bamboo/idris-cil>`__.
103+
104+JVM
105+---
106+
107+`Available online <https://github.com/mmhelloworld/idris-jvm>`__
108+
109+Malfunction
110+------------
111+
112+`Available online <https://github.com/stedolan/idris-malfunction>`__
113+
114+Ocaml
115+-----
116+
117+`Available online <https://github.com/ziman/idris-ocaml>`__
118+
119+
120+WS
121+---
122+
123+`Available online <https://github.com/edwinb/WS-idr>`__
docs/reference/index.rst+1
@@ -20,6 +20,7 @@ This will tell you how Idris works, for using it you should read the Idris Tutor
20.. toctree::
20.. toctree::
21 :maxdepth: 1
21 :maxdepth: 1
22
22
23+ codegen
23 documenting
24 documenting
24 packages
25 packages
25 uniqueness-types
26 uniqueness-types