Supplies #257 roadmap

roadmap/FLAGS.md

@@ -0,0 +1,45 @@
+# Flags
+
+Elchemy compiler for purposes of experimenting and stretching the boundaries accepts flags.
+
+#### DO NOT ATTEMPT TO DO THAT UNLESS YOU'RE SURE IT'S THE ONLY WAY
+
+To pass a flag to a compiler there is a special comment syntax
+
+```
+{- flag flagname:+argument flagname2:+argument2 }
+```
+
+So far there is 4 flag types:
+#### `notype:+TypeName`
+Omits putting the `@type` into the compiled output code  
+Used when you need type checking inside Elchemy ecosystem, without forwarding the definition into the output code.  
+Example:
+```elm
+{- flag notype:+MyHiddenType -}
+type MyHiddenType = Hidden a
+```
+---
+#### `nodef:+functionName`
+Omits entire function definition from the code output. The function `@spec` will still be produced.
+Example:
+```elm
+{- flag nodef:+myHiddenFunction -}
+myHiddenFunction = 1
+```
+---
+#### `nospec:+functionName`
+Omits function spec from the code output
+Example:
+```elm
+{- flag nospec:+myHiddenFunction -}
+myHiddenFunction : Int
+```
+---
+#### `noverify:+functionName`
+Omits function verify macro from the code output. Usable only when using for functions defined as FFI
+Example:
+```elm
+{- flag nospec:+myHiddenFunction -}
+myHiddenFunction : Int
+```

roadmap/INLINING.md

@@ -0,0 +1,17 @@
+# Inlining Elixir Code
+
+
+#### DO NOT ATTEMPT TO DO THAT UNLESS YOU'RE SURE IT'S THE ONLY WAY
+
+In Elchemy it's possible to inline Elixir code using
+
+```elm
+{- ex
+
+## Code
+def any_function() do
+  1
+end
+
+-}
+```

roadmap/INSTALLATION.md

@@ -0,0 +1,67 @@
+# Installation
+
+You can install Elchemy using [npm](https://www.npmjs.com/) with
+```
+npm install -g elchemy
+```
+
+To integrate Elchemy with your project you need to execute:
+
+```
+elchemy init
+```
+
+Inside your elixir project directory.  
+If you don't have a project created, you need to first create it. It's advised to use  [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html#our-first-project) for that.
+
+Assuming the simplest example project called `my_project` the standard path would be:
+
+```
+mix new my_project
+cd my_project
+elchemy init
+```
+
+Then open your `mix.exs` file inside project root directory. And add
+```elixir
+|> Code.eval_file("elchemy.exs").init
+```
+At the end of your `project/0` function definition. Like so:  
+Before:
+```elixir
+defmodule MyProject.Mixfile do
+  use Mix.Project
+
+  def project do
+    [
+      app: :my_project,
+      version: "0.1.0",
+      elixir: "~> 1.5",
+      start_permanent: Mix.env == :prod,
+      deps: deps()
+    ]
+  end
+
+  # Run "mix help compile.app" to learn about applications.
+  def application do
+  ...
+```
+After:
+```elixir
+defmodule MyProject.Mixfile do
+  use Mix.Project
+
+  def project do
+    [
+      app: :my_project,
+      version: "0.1.0",
+      elixir: "~> 1.5",
+      start_permanent: Mix.env == :prod,
+      deps: deps()
+    ] |> Code.eval_file("elchemy.exs").init
+  end
+
+  # Run "mix help compile.app" to learn about applications.
+  def application do
+  ...
+```

roadmap/README.md

@@ -15,6 +15,16 @@ or eventually will have to face
   - [Comments](COMMENTS.md)
   - [Interop (Foreign Function Interface)](INTEROP.md)
 
+## Advanced
+  - [Side Effects / TEA](SIDE_EFFECTS.md)
+  - [Unit Testing](TESTING.md)
+  - [Compiler flags](FLAGS.md)
+  - [Inlining Elixir](INLINING.md)
+
+## Tooling
+  - [Installation](INSTALLATION.md)
+  - [Troubleshooting](TROUBLESHOOTING.md)
+
 # Introduction
 
 
@@ -40,7 +50,7 @@ Elchemy inherits many values from its parents: Elm and Elixir
 - Battle-tested distribution system that just works
 
 ### Additional
-- Foreign function calls type saftety
+- Foreign function calls type safety
 - Foreign function calls purity checks
 - Dependency system based on GitHub
 - Compile time code optimizations

roadmap/SIDE_EFFECTS.md

@@ -0,0 +1,3 @@
+# Side Effects
+
+It's currently impossible to express side effects using Elchemy.

roadmap/TESTING.md

@@ -0,0 +1,4 @@
+# Testing
+
+So far there is no unit testing tool for Elchemy.  
+To test your code use Elixir's `ExUnit` or see document [COMMENTS.md](COMMENTS.md) for using Doctests.

roadmap/TROUBLESHOOTING.md

@@ -0,0 +1,28 @@
+# Troubleshooting
+
+Generally grand amount of problems can be solved with a simple command:
+```
+elchemy clean
+```
+
+It cleans all of the caches, temporary files, dependencies and code file outputs out of the current project.
+
+If
+```
+elchemy clean
+elchemy init
+mix compile
+```
+
+still yields compilation errors feel free to report an issue.
+For the sake of being able to reproduce please provide:
+
+- Elchemy version (`elchemy version`)
+- Elixir version (`elixir -v`)
+- Erlang version (first line in `erl`)
+- Elm version (`elm -v`)
+- Operating system (`uname -msr`)
+
+It's also helpful to include:
+- Result of `tree -L 2` inside your project folder
+- Code of the file failing