diff options
Diffstat (limited to 'docs/using.en.md')
-rw-r--r-- | docs/using.en.md | 66 |
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`. |