@@ -6,33 +6,47 @@ uid: Kaleidoscope-ch1
66# 1. Kaleidoscope: Language Introduction
77The general flow of this tutorial follows that of the official
88[ LLVM tutorial] ( xref:llvm_kaleidoscope_tutorial )
9- and many of the samples are lifted directly from that tutorial to make it easier to follow
10- along both tutorials to see how the various LLVM concepts are projected in the Ubiquity.NET.Llvm library.
9+ and many of the samples are lifted directly from that tutorial to make it easier to
10+ follow along both tutorials to see how the various LLVM concepts are projected in the
11+ Ubiquity.NET.Llvm library.
12+
13+ > [ !NOTE]
14+ > The samples are all setup to include ` <PublishAot>True</PublishAot> ` and therefore
15+ > support AOT code generation. To use that you only need to run
16+ > ` dotnet publish <project path> -r win-x64 ` to build the native standalone version
17+ > of the app. This demonstrates that the libraries are AOT compatible. While this makes
18+ > things run faster as no JIT used, everything is already native code, it has the
19+ > drawback of making the app RID specific. That is, you must AOT build for EVERY
20+ > supported RID target. Thus, every use must make a choice and there is no single
21+ > "one size fits all" answer.
1122
1223## Overview
13- Kaleidoscope is a simple functional language that is used to illustrate numerous real world
14- use cases for Ubiquity.NET.Llvm for code generation and JIT execution.
24+ Kaleidoscope is a simple functional language that is used to illustrate numerous real
25+ world use cases for Ubiquity.NET.Llvm for code generation and JIT execution.
1526
16- It is worth pointing out that this example is not intended as a treatise on compiler design nor
17- on language parsing. While it contains many aspects of those topics the tutorial is, mostly, focused
18- on the use of Ubiquity.NET.Llvm for code generation. Furthermore it isn't a trans-literation of the LLVM C++
19- sample as that would defeat one of the major points of Ubiquity.NET.Llvm - to provide a familiar API and
20- use pattern to C# developers.
27+ It is worth pointing out that this example is not intended as a treatise on compiler
28+ design nor on language parsing. While it contains many aspects of those topics the
29+ tutorial is, mostly, focused on the use of Ubiquity.NET.Llvm for code generation.
30+ Furthermore it isn't a trans-literation of the LLVM C++ sample as that would defeat
31+ one of the major points of Ubiquity.NET.Llvm - to provide a familiar API and use
32+ pattern to C# developers.
2133
2234## General layout
23- The samples are built using common core libraries and patterns. They are explicitly designed to
24- make code comparisons between chapters via your favorite code comparison tool. Each, chapter builds
25- on the next so running a comparison makes it easy to see the changes in full context. The text of
26- the tutorials explains why the changes are made and a comparison helps provide the "big picture"
27- view.
35+ The samples are built using common core libraries and patterns. They are explicitly
36+ designed to make code comparisons between chapters via your favorite code comparison
37+ tool. Each, chapter builds on the next so running a comparison makes it easy to see
38+ the changes in full context. The text of the tutorials explains why the changes are
39+ made and a comparison helps provide the "big picture" view.
2840
2941## Variations from the Official LLVM Tutorial
30- The Ubiquity.NET.Llvm version of the Kaleidoscope series takes a different route for parsing from the
31- LLVM implementation. In particular the Ubiquity.NET.Llvm version defines a formal grammar using
32- [ ANTLR4] ( http://antlr.org ) with the full grammar for all variations of the language features in
33- a single assembly. Ultimately the parsing produces an [ AST] ( xref:Kaleidoscope-AST ) so that the actual
34- technology used for the parse is hidden as an implementation detail. This helps in isolating the parsing
35- from the use of Ubiquity.NET.Llvm for code generation and JIT compilation for interactive languages.
42+ The Ubiquity.NET.Llvm version of the Kaleidoscope series takes a different route for
43+ parsing from the LLVM implementation. In particular the Ubiquity.NET.Llvm version
44+ defines a formal grammar using [ ANTLR4] ( http://antlr.org ) with the full grammar for
45+ all variations of the language features in a single assembly. Ultimately the parsing
46+ produces an [ AST] ( xref:Kaleidoscope-AST ) so that the actual technology used for the
47+ parse is hidden as an implementation detail. This helps in isolating the parsing from
48+ the use of Ubiquity.NET.Llvm for code generation and JIT compilation for interactive
49+ languages.
3650
3751## The Kaleidoscope Language
3852### General Concepts
@@ -44,43 +58,52 @@ Kaleidoscope is a simple functional language with the following major features:
4458* For loop style control flow
4559* User defined operators
4660 - User defined operators can specify operator precedence
47- - User defined precedence is arguably the most complex part of parsing and implementing the language.
48- Though, ANTLR4's flexibility made it fairly easy to do once fully understood. (more details in
49- [ Chapter 6] ( xref:Kaleidoscope-ch6 ) )
61+ - User defined precedence is arguably the most complex part of parsing and
62+ implementing the language. Though, ANTLR4's flexibility made it fairly easy to
63+ do once fully understood. (more details in [ Chapter 6] ( xref:Kaleidoscope-ch6 ) )
5064
5165### Expressions
52- In Kaleidoscope, everything is an expression (e.g. everything has or returns a value even if the value
53- is a constant 0.0). There are no statements and no "void" functions etc...
66+ In Kaleidoscope, everything is an expression (e.g. everything has or returns a value
67+ even if the value is a constant 0.0). There are no statements and no "void" functions
68+ etc...
5469
5570#### Multi-line expressions
56- There are a few different ways to represent an expression that is long enough to warrant splitting it across
57- multiple lines when typing it out.
71+ There are a few different ways to represent an expression that is long enough to
72+ warrant splitting it across multiple lines when typing it out.
5873
5974##### Expression Continuation Marker
60- One mechanism for handling multi-line expressions that is used in most shell scripting languages is a line
61- continuation marker. In such cases a special character followed by a line-termination char or char sequence
62- indicates that the expression continues on the next line (e.g. it isn't complete yet).
75+ One mechanism for handling multi-line expressions that is used in most shell scripting
76+ languages is a line continuation marker. In such cases a special character followed by
77+ a line-termination char or char sequence indicates that the expression continues on
78+ the next line (e.g. it isn't complete yet).
6379
6480##### Expression Complete Marker
65- Another approach to handling long expressions spanning multiple lines is basically the opposite of line
66- continuation, expression complete markers. This marker indicates the end of a potentially multi-line expression. (A variant
67- of this might require a line termination following the marker as with the line continuation).
81+ Another approach to handling long expressions spanning multiple lines is basically the
82+ opposite of line continuation, expression complete markers. This marker indicates the
83+ end of a potentially multi-line expression. (A variant of this might require a line
84+ termination following the marker as with the line continuation).
6885
6986##### Kaleidoscope Implementation
70- The original LLVM C++ implementation chose the expression completion approach using a semicolon as the completion.
71- (So it seems familiar like statements in other C like languages) Therefore, the Ubiquity.NET.Llvm tutorial follows the same
72- design. [ Implementing the line continuation mechanism in Kaleidoscope is left as an exercise for the reader :wink : ]
87+ The original LLVM C++ implementation chose the expression completion approach using a
88+ semicolon as the completion. (So it seems familiar like statements in other C like
89+ languages) Therefore, the Ubiquity.NET.Llvm tutorial follows the same design.
90+ [ Implementing the line continuation mechanism in Kaleidoscope is left as an exercise
91+ for the reader - though if you come up with a mechanism to support either that is
92+ determined by the calling application; PRs are welcome! :wink : ]
7393
7494### Example
75- The following example is a complete program in Kaleidoscope that will generate a textual representation
76- of the classic Mandelbrot Set.
95+ The following example is a complete program in Kaleidoscope that will generate a
96+ textual representation of the classic Mandelbrot Set.
7797
7898[ !code-Kaleidoscope[ mandel.kls] ( mandel.kls )]
7999
80- When entered ( or copy/pasted) to the command line Kaleidoscope will print out the following:
100+ When entered ( or copy/pasted) to the command line Kaleidoscope will print out the
101+ following:
102+
81103> [ !NOTE]
82- > This example uses features of the language only enabled/discussed in Chapter 6 of the tutorial.
83- > The runtime from chapters 3-5 will generate errors trying to parse this code.
104+ > This example uses features of the language only enabled/discussed in Chapter 6 of the
105+ > tutorial.The runtime from chapters 3-5 will generate errors trying to parse this
106+ > code.
84107
85108``` shell
86109Ready> mandel(-2.3, -1.3, 0.05, 0.07);
@@ -130,8 +153,9 @@ Ready>
130153```
131154
132155## Conclusion
133- Kaleidoscope is a simple, yet complete, language with a good deal of functionality. This serves as
134- a great language to study the use of Ubiquity.NET.Llvm for code generation and Domain Specific
135- Languages. While, generally speaking, the functionality of the Ubiquity.NET.Llvm version of this
136- tutorial differs only slightly from that of the official LLVM version, it serves well as an example
137- of what you can do with Ubiquity.NET.Llvm.
156+ Kaleidoscope is a simple, yet complete, language with a good deal of functionality.
157+ This serves as a great language to study the use of Ubiquity.NET.Llvm for code
158+ generation and Domain Specific Languages. While, generally speaking, the functionality
159+ of the Ubiquity.NET.Llvm version of this tutorial differs only slightly from that of
160+ the official LLVM version, it serves well as an example of what you can do with
161+ Ubiquity.NET.Llvm.
0 commit comments