Ironclad is a kernel for several architectures, supporting general-purpose and
embedded modes, written in Ada.

For more information about the project, check https://nongnu.org/ironclad

-- Building --

The steps for building using gprbuild are:

gprbuild -p ironclad.gpr -j4 # Build the kernel.
./install.sh                 # Install.

To run the formal proofing framework, which is not necessary, one can run:

gnatprove -P ironclad.gpr -U --prover=cvc4,altergo,z3 --mode=all -j4

Several flags and variables are available for tuning:

- ARCH, right now "x86_64-stivale2" and "aarch64-stivale2" are available.
- TARGET, visited in the "Big and small targets" section.
- ALLOC_SCHEME, visited in the "Allocation schemes" section.
- ADAFLAGS, ASMFLAGS, and LDFLAGS, passed as environment variables to gprbuild.
- DESTDIR and PREFIX for ./install.sh.
- Pass 'strip' as the only argument to ./install.sh for stripped binaries.

A list of the tools needed for compilation and checked by configure is:

- gprbuild and a compatible Ada and C compilers.
- gnatprove for formal proofing if desired.
- GNU Info for building the documentation with Info and PDF support.

A good set of flags for a release build is:

ADAFLAGS='-flto -O2' CFLAGS='-flto -O2' LDFLAGS='-flto -O2'

-- Big and small targets --

Ironclad supports two main build-time configurations, ruled by the TARGET
variable, which depending on the value will take the following meanings:

- TARGET="big": Normal configuration of the kernel for general-purpose
usecases. All drivers will be cooked in regardless of system footprint.

- TARGET="small": Superfluous drivers will be left out, building a minimal yet
lightweight system.

"big" is the default for the flag.

-- Allocation schemes --

Two memory allocation schemes are supported, deep information about them is
given on the documentation, but this are the options and a short description:

- ALLOC_SCHEME="standard": General-purpose allocation algorithm that supports
freeing memory.

- ALLOC_SCHEME="alloconly": More efficient allocator, which uses less memory
and is faster but cannot free.

-- Documentation --

The project features info and PDF files generated from the texinfo source in
the docs subdirectory, and they are generated and installed automatically when
running ./install.sh.

The generated documentation features information about a lot of kernel-specific
concepts along with syscall listings and project information. Apart of that,
there is this README and a CONTRIBUTING.md with contributing guidelines in the
root directory of the project.

Generated documentation is hosted and updated regularly online at:
https://www.nongnu.org/ironclad/manual/ - HTML format.
https://www.nongnu.org/ironclad/manual/ironclad.pdf - PDF format.

-- Thanks to --

- Mintsuki (https://github.com/mintsuki) et al - For the
Limine (https://github.com/limine-bootloader/limine) project, used for testing
and code reference.

- The managarm project (https://github.com/managarm), used for code
reference for the aarch64 port, and Qookie, one of the maintainers, for help
debugging.

- The FlorenceOS project (https://github.com/FlorenceOS) for code reference
for the aarch64 MMU, and N00byEdge, one of the maintainers, for help
debugging the obscure and esoteric issues.

========================================================================

Copyright (C) 2022 streaksu, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the "GNU Free
Documentation License" file as part of this distribution.
