Merge branch 'master' into method_impl

Author: riederm

.github/workflows/doc.yml

@@ -5,6 +5,10 @@ on:
   pull_request:
     branches: [ master ]
 
+env:
+  toolchain-version: 1.53.0
+  llvm-version: "11.0.1"
+
 jobs:
   cargo-docs:
     runs-on: ubuntu-latest
@@ -19,6 +23,11 @@ jobs:
         uses: peaceiris/actions-mdbook@v1
         with:
           mdbook-version: 'latest'
+      - name: Install LLVM
+        uses: ghaith/install-llvm-action@latest
+        with:
+          version: ${{ env.llvm-version }}
+          directory: "./llvm"
       - name: Build API documentation
         uses: actions-rs/cargo@v1
         with:

.github/workflows/rust.yml

@@ -33,6 +33,7 @@ jobs:
         uses: ghaith/install-llvm-action@latest
         with:
           version: ${{ env.llvm-version }}
+          directory: "./llvm"
 
       - name: Cargo check
         uses: actions-rs/cargo@v1
@@ -114,6 +115,12 @@ jobs:
           override: true
           components: clippy, rustfmt
 
+      - name: Install LLVM
+        uses: ghaith/install-llvm-action@latest
+        with:
+          version: ${{ env.llvm-version }}
+          directory: "./llvm"
+
       - name: Run cargo fmt
         uses: actions-rs/cargo@v1
         with:

.gitignore

@@ -5,3 +5,5 @@
 *.ir
 *.o
 *.bc
+*.a
+*.elf

Cargo.lock

@@ -21,6 +21,7 @@ glob = "0.3.0"
 encoding_rs = "0.8"
 encoding_rs_io = "0.1"
 codespan-reporting = "0.11.1"
+mun_lld = "110.0.0"
 
 
 [lib]

Cargo.toml

@@ -3,7 +3,7 @@
 ## Prerequisites
 To be able to build the source code, you will need to [install Rust](https://www.rust-lang.org/tools/install)
 and LLVM 11, along with the standard build tools (`build-essential`) and `libz-dev` on your machine.
-For Linux the package manager version of LLVM (e.g. `llvm-11-dev` for apt) will work fine, for Windows, you need a
+For Linux the package manager version of LLVM (e.g. `llvm-11-dev`, `liblld-11-dev` for apt) will work fine, for Windows, you need a
 [special build](https://github.com/ghaith/llvm-package-windows/releases/tag/v11.0.1). If you want to
 clone and work on the repository, you'll also need _git_.
 

book/src/build_and_install.md

@@ -8,6 +8,8 @@ puts out static or shared objects as well as LLVM IR or bitcode by the flip of
 a command line flag. We are aiming towards an open-source industry-grade ST compiler
 supporting at least the features in 2nd edition IEC 61131 standard. 
 
+You might also want to refer to the [API documentation](https://ghaith.github.io/rusty/api/rusty/).
+
 ## Supported Language Concepts
 ### POUs
 - ✔ Program
@@ -40,13 +42,15 @@ supporting at least the features in 2nd edition IEC 61131 standard.
 - ✔ Call statements
 - ✔ Implicit call arguments
 - ✔ Explicit call arguments
+- ✔ EXIT, CONTINUE statements
 
 ### Control Structures
 - ✔ IF Statement
 - ✔ CASE Statement
 - ✔ FOR Loops
 - ✔ WHILE Loops
 - ✔ REPEAT Loops
+- ✔ RETURN statement
 
 ### Expressions
 - ✔ Arithmetic Operators

book/src/intro_1.md

@@ -22,12 +22,53 @@ More examples:
 - `rustyc --ir src/*.st` will compile all st files in the src-folder.
 - `rustyc --ir "**/*.st"` will compile all st-files in the current folder and its subfolders recursively.
 
-## Compiling a static object
+## Example: Building a hello world program
+### Writing the code
+We want to print something to the terminal, so we're going to declare external functions
+for that and link with libc when we're done. This program can also be found at
+`examples/hello_world.st` in the source tree of Rusty. 
 
-## Compiling a linkable object
+* `_start` is our entry point to the program, because most linker scripts define it this way. 
 
-## Creating a shared library 
+* Since we don't have a `crt0` right now, we have to call the `exit()` function by ourselves after we're
+done. Otherwise, the program will most likely crash (because it tries to return to a function that never
+existed).
 
-## Linking with an external application
+```st
+@EXTERNAL FUNCTION puts : DINT
+VAR_INPUT
+    text : STRING;
+END_VAR
+END_FUNCTION
 
-## Writing a main
+@EXTERNAL FUNCTION exit : DINT
+VAR_INPUT
+    status : DINT;
+END_VAR
+END_FUNCTION
+
+FUNCTION _start : DINT
+    puts('hello, world!');
+    exit(0);
+END_FUNCTION
+```
+
+### Compiling with rusty
+Compiling with rusty is very easy. If you just want to build an object file, then do this:
+```bash
+rustyc -c hello_world.st -o hello_world.o
+```
+
+### Linking an executable
+Instead, you can also compile this into an executable and run it:
+```bash
+rustyc hello_world.st -o hello_world -L/path/to/libs -lc
+./hello_world
+```
+
+Please note that RuSTy will attempt to link the generated object file by default to generate
+an executable if you didn't specify something else (option `-c`).
+* The `-lc` flag tells the linker it should link against `libc`. Depending on the available libraries on your system,
+the linker will prefer a dynamically linked library if available, and revert to a static one otherwise.
+* You add library search pathes by providing additional `-L /path/...` options. By default, this will be
+the current directory.

book/src/using_rusty.md

@@ -4,14 +4,13 @@ VAR_INPUT
 END_VAR
 END_FUNCTION
 
-@EXTERNAL FUNCTION exit : __VOID
-    VAR_INPUT status : DINT; END_VAR
-END_FUNCTION
-
-FUNCTION main : DINT
-	puts('hello, world');
+@EXTERNAL FUNCTION exit : DINT
+VAR_INPUT
+    status : DINT;
+END_VAR
 END_FUNCTION
 
 FUNCTION _start : DINT
-    exit(main(0));
-END_FUNCTION 
+	puts('hello, world!');
+    exit(0);
+END_FUNCTION

examples/hello_world.st

@@ -62,6 +62,9 @@ pub struct CompileParameters {
     )]
     pub output_bit_code: bool,
 
+    #[structopt(short = "c", help = "Do not link after compiling object code")]
+    pub skip_linking: bool,
+
     #[structopt(
         long,
         name = "target-triple",
@@ -85,6 +88,17 @@ pub struct CompileParameters {
     )]
     // having a vec allows bash to resolve *.st itself
     pub input: Vec<String>,
+
+    #[structopt(
+        name = "library-path",
+        long,
+        short = "L",
+        help = "Search path for libraries, used for linking"
+    )]
+    pub library_pathes: Vec<String>,
+
+    #[structopt(name = "library", long, short = "l", help = "Library name to link")]
+    pub libraries: Vec<String>,
 }
 
 fn parse_encoding(encoding: &str) -> Result<&'static Encoding, String> {
@@ -122,20 +136,21 @@ impl CompileParameters {
 
     /// return the output filename with the correct ending
     pub fn output_name(&self) -> Option<String> {
+        let out_format = self.output_format_or_default();
         if let Some(n) = &self.output {
             Some(n.to_string())
         } else {
-            let ending = match self.output_format_or_default() {
-                FormatOption::Bitcode => "bc",
-                FormatOption::Static => "o",
-                FormatOption::Shared => "so",
-                FormatOption::PIC => "so",
-                FormatOption::IR => "ir",
+            let ending = match out_format {
+                FormatOption::Bitcode => ".bc",
+                FormatOption::Static if self.skip_linking => ".o",
+                FormatOption::Static => "",
+                FormatOption::Shared | FormatOption::PIC => ".so",
+                FormatOption::IR => ".ir",
             };
 
             let output_name = self.input.first().unwrap();
             let basename = Path::new(output_name).file_stem()?.to_str()?;
-            Some(format!("{}.{}", basename, ending))
+            Some(format!("{}{}", basename, ending))
         }
     }
 }
@@ -234,13 +249,17 @@ mod cli_tests {
         assert_eq!(parameters.output_name().unwrap(), "charlie.so".to_string());
 
         let parameters =
-            CompileParameters::parse(vec_of_strings!("examples/test/delta.st", "--static"))
+            CompileParameters::parse(vec_of_strings!("examples/test/delta.st", "--static", "-c"))
                 .unwrap();
         assert_eq!(parameters.output_name().unwrap(), "delta.o".to_string());
 
         let parameters =
             CompileParameters::parse(vec_of_strings!("examples/test/echo", "--bc")).unwrap();
         assert_eq!(parameters.output_name().unwrap(), "echo.bc".to_string());
+
+        let parameters =
+            CompileParameters::parse(vec_of_strings!("examples/test/echo.st")).unwrap();
+        assert_eq!(parameters.output_name().unwrap(), "echo".to_string());
     }
 
     #[test]
@@ -338,6 +357,35 @@ mod cli_tests {
         assert_eq!(parameters.output_shared_obj, false);
     }
 
+    #[test]
+    fn library_path_added() {
+        let parameters = CompileParameters::parse(vec_of_strings!(
+            "input.st",
+            "--library-path",
+            "xxx",
+            "-L",
+            "test",
+            "-L.",
+            "-L/tmp"
+        ))
+        .unwrap();
+        assert_eq!(parameters.library_pathes, vec!["xxx", "test", ".", "/tmp"]);
+    }
+
+    #[test]
+    fn libraries_added() {
+        let parameters = CompileParameters::parse(vec_of_strings!(
+            "input.st",
+            "-l",
+            "test",
+            "-lc",
+            "--library",
+            "xx"
+        ))
+        .unwrap();
+        assert_eq!(parameters.libraries, vec!["test", "c", "xx"]);
+    }
+
     #[test]
     fn cli_supports_version() {
         match CompileParameters::parse(vec_of_strings!("input.st", "--version")) {

src/cli.rs

@@ -39,6 +39,9 @@ pub enum CompileError {
 
     #[error("Cannot write File {path:}: {reason:}")]
     IoWriteError { path: String, reason: String },
+
+    #[error("Cannot link: {reason:}")]
+    LinkerError { reason: String },
 }
 
 impl From<Diagnostic> for CompileError {