aboutsummaryrefslogtreecommitdiff
path: root/docs/using.en.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/using.en.md')
-rw-r--r--docs/using.en.md66
1 files changed, 66 insertions, 0 deletions
diff --git a/docs/using.en.md b/docs/using.en.md
new file mode 100644
index 0000000..d77204c
--- /dev/null
+++ b/docs/using.en.md
@@ -0,0 +1,66 @@
+---
+title: Building and using libcarrot
+---
+Once you've acknowledged (the basic principles of libcarrot)[index], you can
+start building it.
+
+# Requirements
+You will need Python 3.x to run the build tool, with the modules described
+in the `requirements.txt` file, which you can install using
+`pip3 install -r requirements.txt` as root/administrator.
+
+Other dependencies (compilers, assemblers, linkers, packers, ...) are optional,
+and should be tipped off by the tools.
+
+# Configuring
+This project uses the Unix building flow, which means you shall first
+configure with the options that suit your needs, then make (build), then
+install, in three different commands. On Unix-like OSes, this can be achieved
+using the famous `./configure && make && sudo make install` bash command;
+but I'll suppose you want to go a little deeper into its options.
+
+The 'real' configure script is in `tool/configure.py`, though it can be
+accessed under Unix-like OSes through the `configure` bash script and under
+Microsoft Windows' command shell through the `configure.bat` script,
+for simplicity. `-h`/`--help` prints the help message, listing the options
+and a little help message, `-v`/`--version` prints the project version.
+
+libcarrot can build for several targets, which combine platforms and
+architectures:
+
+- an architecture represents the hardware (or hardware emulation layer) on
+which the code will run, more specifically the processor. For example,
+the Intel i686 microprocessor, or the SuperH Core 3 (SH3);
+- a platform represents the software on which the C library is running,
+generally the kernel, like the Linux kernel (`linux`) or CASIOWIN (the
+OS CASIO uses on its graphing calculators).
+
+To select the target, you shall use the `--target` option with the value
+being the architecture then the platform, separated with a dash, e.g.
+`sh3-casiowin` for CASIOWIN on a SuperH Core 3 microprocessor.
+
+You can also select the programming languages libcarrot shall support with
+the `--languages` option, with the languages being separated with commas,
+for example, `--languages=c,c++`. libcarrot currently only supports C.
+
+In addition to this, there is the `--add` option to add additional modules
+to the usual selected one. For example, if you're allowing yourself some
+fantasy, you can add the `all/stdcocorico` module, which will add the
+joke `stdcocorico.h` header to your programs so you can code in a french
+C or C++ dialect.
+
+Once you've fiddled with the configure options, you can select the
+installation directories and options! (TODO: document these once they're ready)
+
+# Building and installing
+
+Once the project is configured, you can `make` under UNIX-like OSes,
+`make.bat` under Microsft Windows (using the command shell), or
+`tools/make.py` on any other platform.
+
+There are actually a few other commands you can do with `make`, such as
+`clean` to remove generated files (excepted the configuration),
+`mrproper` or `distclean` to remove everything (including the configuration),
+`re` to remake everything (expected the configuration).
+
+To install the library, use `make install`.