Appendix H: Aedifex

3 files changed, 223 insertions, 1 deletions

diff --git a/documentation/book/the_lux_programming_language/appendix_h.md b/documentation/book/the_lux_programming_language/appendix_h.md
new file mode 100644
index 000000000..a4ba8d6b1
--- /dev/null
+++ b/documentation/book/the_lux_programming_language/appendix_h.md
@@ -0,0 +1,218 @@
+# Appendix H: Aedifex
+
+Aedifex is a fairly basic build tool, but it offers the necessary commands to handle a normal Lux project.
+
+It offers a small set of commands, and a few convenience features.
+
+```
+lux version
+
+=>
+
+00.06.00
+```
+
+This command tells you the version of Aedifex you're using.
+
+This version is also the same as the version of the Lux compiler Aedifex has been designed to work with.
+
+So, you can also think of this as being the version of the language that is best supported by Aedifex (although not necessarily the only version that is supported).
+
+```
+lux clean
+
+=>
+
+Successfully cleaned target directory: target
+```
+
+This command cleans up any compilation artifacts and caching artifacts left over by previous compilations/builds of your Lux project.
+
+```
+lux pom
+
+=>
+
+Successfully created POM file: pom.xml
+```
+
+This command generates a Maven POM file that reflects the contents of the `project.lux` file made for Aedifex.
+
+```
+lux deps
+
+=>
+
+[?] Fetching com.github.luxlang:lux-jvm-0.6.0 from "~/.m2/repository"
+[O] Found com.github.luxlang:lux-jvm-0.6.0 at "~/.m2/repository"
+ Local successes: 0: "com.github.luxlang:lux-jvm-0.6.0"
+  Local failures: 
+Remote successes: 
+ Remote failures:
+```
+
+This commands fetches all dependencies from the available repositories (plus the local Maven repository/cache), and installs any dependencies that had to be fetched remotely into the local Maven repository/cache.
+
+```
+lux install
+
+=>
+
+Successfully installed the project locally.
+```
+
+This command packages your project into a TAR archive and installs it into the local Maven repository/cache, to be used as a dependency.
+
+```
+lux deploy <deploy_repository> <user_name> <password>
+
+## For example:
+
+lux deploy snapshots foo bar_baz_quux
+
+=>
+
+Successfully deployed the project.
+```
+
+This command packages your project into a TAR archive and deploys it to a remote Maven repository, to be used as a dependency.
+
+```
+lux build
+```
+
+This command build your project into an executable program, named `program.`(`jar`|`js`|`lua`|`py`|`rb`) depending on the chosen compilation target, and located under the target directory (`target` by default).
+
+```
+lux test
+```
+
+This command build your project into an executable program, and then executes it and display any STDOUT/STDERR logging output on the terminal/console.
+
+This is the main mechanism to run automated tests for your Lux project.
+
+```
+lux auto build
+
+## OR
+
+lux auto test
+```
+
+This works the same as the normal versions of the command, but Aedifex also watches over the files in your source directories and every time a file changes, it automatically builds/tests the project for you.
+
+This is extremely useful when fixing typing errors iteratively, or when debugging errors raised during your tests, as it saves you having to constantly re-build/re-run the project every time you want to try the latest changes.
+
+```
+lux with <profile> <command>
+
+## For example:
+
+lux with jvm with bibliotheca auto test
+```
+
+This command composes non-default profiles with the default one to generate the profile to use when executing a command.
+
+This allows you to segregate useful configuration into different profiles and then combine them based on what you need at a given time.
+
+---
+
+Now that we have seen the available commands, it would be useful to see an annotated example `project.lux` file to see what bits of configuration it can contain.
+
+```
+["" ... The empty text ("") is used to specify the default profile.
+ [... An optional identity for the project.
+  ... It can also be specified or overriden in a non-default profile.
+  ... This will be the name given to the project when installed/deployed as a dependency.
+  #identity ["com.github.luxlang" "stdlib" "0.6.0"]
+
+  ... Every piece of information, and the whole #info bundle, are optional.
+  #info [#url "https://github.com/LuxLang/lux"
+         #scm "https://github.com/LuxLang/lux.git"
+         #licenses [[#name "Lux License v0.1.1"
+                     #url "https://github.com/LuxLang/lux/blob/master/license.txt"
+                     #type #repo]]
+         ... #organization [[#name "Lux Foundation"
+         ...                 #url "http://example.com/lux_foundation"]]
+         #developers [[#name "Eduardo Julian"
+                       #url "https://github.com/eduardoejp"
+                       ... #organization [#name "Lux Foundation"
+                       ...                #url "http://example.com/lux_foundation"]
+                       ]]
+         ... #contributors [[#name "Eduardo Julian"
+         ...                 #url "https://github.com/eduardoejp"
+         ...                 #organization [#name "Lux Foundation"
+         ...                                #url "http://example.com/lux_foundation"]]]
+         ]
+
+  ... An optional list of repositories you can deploy to, given aliases so they're easy to refer to with the "deploy" command.
+  #deploy_repositories ["snapshots" "https://oss.sonatype.org/content/repositories/snapshots/"
+                        "releases" "https://oss.sonatype.org/service/local/staging/deploy/maven2/"]
+
+  ... An optional list of repositories to use for fetching remote dependencies.
+  ... Additionally, there is an implicit repository being used, which is https://repo1.maven.org/maven2/
+  ... So, even if the #repositories list were to be empty, you'd still have access to the default repository.
+  #repositories ["https://oss.sonatype.org/content/repositories/snapshots/"
+                 "https://oss.sonatype.org/service/local/staging/deploy/maven2/"]
+  ... The different directories to look for source code. The default is described below.
+  ... #sources ["source"]
+  ... The directory for storing the build artifacts. The default is described below.
+  ... #target "target"
+  ]
+
+ ... The following are alternative profiles to use in various situations.
+ "jvm"
+ [... #compiler specifies the dependency to fetch and use as the compiler.
+  #compiler ["com.github.luxlang" "lux-jvm" "0.6.0" "jar"]
+  ... #dependencies is an optional list of dependencies to fetch.
+  ... The dependencies have the same shape as when specifying the compiler.
+  ... When omitting the packaging format of the dependency, "tar" will be assumed.
+  ... #dependencies [["org.ow2.asm" "asm-all" "5.0.3" "jar"]
+  ...                ["com.github.luxlang" "stdlib" "0.6.0"]]
+  ... The OS command to use when running JVM tests. The default is described below.
+  ... #java ["java" "-jar"]
+  ]
+
+ "js"
+ [#compiler ["com.github.luxlang" "lux-js" "0.6.0" "js"]
+  ... The OS command to use when running JS tests. The default is described below.
+  ... #js ["node" "--stack_size=8192"]
+  ]
+
+ "python"
+ [#compiler ["com.github.luxlang" "lux-python" "0.6.0" "jar"]
+  ... The OS command to use when running Python tests. The default is described below.
+  ... #python ["python3"]
+  ]
+
+ "lua"
+ [#compiler ["com.github.luxlang" "lux-lua" "0.6.0" "jar"]
+  ... The OS command to use when running Lua tests. The default is described below.
+  ... #lua ["lua"]
+  ]
+
+ "ruby"
+ [#compiler ["com.github.luxlang" "lux-ruby" "0.6.0" "jar"]
+  ... The OS command to use when running Ruby tests. The default is described below.
+  ... #ruby ["ruby"]
+  ]
+
+ "bibliotheca"
+ [#info [#description "Standard library for the Lux programming language."]
+  #test "test/lux"]
+
+ "documentation"
+ [#program "documentation/lux"
+  #test "documentation/lux"]
+
+ "aedifex"
+ [#info [#description "A build system/tool made exclusively for Lux."]
+  ... Parent profiles to this one.
+  ... Specifying them here is like automatically using Aedifex's "with" command.
+  #parents ["jvm"]
+  ... The name of the main module of the program.
+  #program "program/aedifex"
+  ... The name of the main module where the tests are located.
+  #test "test/aedifex"]]
+```
+
diff --git a/documentation/book/the_lux_programming_language/chapter_1.md b/documentation/book/the_lux_programming_language/chapter_1.md
index 6cd68614f..bb9156cfa 100644
--- a/documentation/book/the_lux_programming_language/chapter_1.md
+++ b/documentation/book/the_lux_programming_language/chapter_1.md
@@ -19,7 +19,7 @@ The instructions for how to install it are at the link and it won't take much ti
 
 ## Question #2: How do I build Lux programs?
 
-Lux uses a custom-made build tool named Aedifex which is configured using a declarative Lux-based syntax.
+Lux uses a custom-made build tool named _Aedifex_ which is configured using a declarative Lux-based syntax.
 To install Aedifex, go to https://github.com/LuxLang/lux/tree/master/shell and download either `lux.bat` or `lux.sh` depending on whether you're on Windows or Linux/Mac.
 Also download the `aedifex.jar` file, and place it (along with either of the scripts you downloaded) somewhere in your `PATH`.
 Now, you'll have access to the `lux` command, which allows you to run Aedifex to build and test Lux projects.
@@ -83,6 +83,8 @@ A directory named `target` will have been created, containing everything that wa
 6. Run the program with this command: `java -jar target/jvm/program.jar`
 7. Smile :)
 
+	For a thorough specification of what Aedifex can do, please refer to [Appendix H](appendix_h.md).
+
 ## Question #4: Where can I find documentation for Lux?
 
 A specially useful source of information is [the documentation for the standard library](https://luxlang.github.io/lux/).
diff --git a/documentation/book/the_lux_programming_language/index.md b/documentation/book/the_lux_programming_language/index.md
index 4351f0be7..17fdd3a7f 100644
--- a/documentation/book/the_lux_programming_language/index.md
+++ b/documentation/book/the_lux_programming_language/index.md
@@ -33,6 +33,7 @@
 	_Where you will learn a new way to organize your data._
 * [Chapter 16: Testing](chapter_16.md)
 	_Where you will learn how to avoid annoying bug reports._
+* [Conclusion](conclusion.md)
 * [Appendix A: Import syntax](appendix_a.md)
 * [Appendix B: Math](appendix_b.md)
 * [Appendix C: Pattern-matching macros](appendix_c.md)
@@ -40,4 +41,5 @@
 * [Appendix E: Lux implementation details](appendix_e.md)
 * [Appendix F: Implicit polymorphism](appendix_f.md)
 * [Appendix G: Regular expressions](appendix_g.md)
+* [Appendix H: Aedifex](appendix_h.md)