diff options
Diffstat (limited to 'documentation/book')
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) |