aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 6b938b3d9c4e72b018b15f02ef9fe5f261571fa4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# libcarrot - an experimental and modular libc for learning
## Introduction

Although originally made to replace CASIO's fxlib under Linux, libcarrot has
now become a more global static standard library for C and C++, originally
targetting the SuperH/J-Core platform, with extensions for the CASIO fx-9860G,
but now aiming to have extensions for more platforms and languages.

The library aims at being compatible with the ISO C and C++ standards,
POSIX/Single Unix Specification, other standards the GNU C library supports,
and at being usable with several compilers such as Hitachi/Renesas' C/C++
compiler (SHC), the GNU Compiler Collection (GCC), the Small Device C Compiler
(SDCC), IBM's XL C/C++ Compiler (XLC), and many more!

It is organized using modules, regrouped by platform, e.g. `linux` or `win32`.
When compiling for a platform, modules will be taken from `all` (common to
all platforms), from your platform's folder, and eventually from others that
are compatible. You can add some additional modules on top of that for
non-essential features or compatibility with some exotic programs.

## Setting it all up
### Requirements

You will need Python 3.x to run the build tool, with the following modules
(you should install them using `pip`):  
- `PyYAML` (YAML file parser).

Other dependencies are optional, and should be tipped off by this tool.  
Here are the toolchains you can use:  
- the GNU toolchain: `sh3eb-elf-gcc`, `sh3eb-elf-as`, `sh3eb-elf-as`;
- the Renesas toolchain: `shc.exe`, `asmsh.exe`, `LnkSpawn.exe`.

### Configuring

The project uses the Unix style of building, which means you shall first
configure with the options that suit you, 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`.

## Contributing

Advanced instructions for what to do, how to do it and stuff, start in the
`CONTRIBUTING.md` file!