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

-- 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.

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.

-- Building and testing --

The tools needed are:

- gprbuild for compilation.
- A compatible Ada compiler, and an assembler for the desired architecture.
- GNU Info for building the documentation with Info and PDF support.
- gnatprove for formal verification, if desired.

For building the project's binaries, using gprbuild like the following works:

gprbuild -p ironclad.gpr -j4

Several environment variables are available for tweaking the kernel, the
options are also tackled in length in the documentation:

- ARCH: Chooses which architecture to target, the supported values are:
     aarch64-stivale2    aarch64 for stivale2-capable bootloaders.
     sparc-leon3         LEON3 boards.
     x86_64-multiboot2   x86_64 for multiboot2-capable bootloaders.

- TARGET: The following values are provided:
     big     All drivers will be cooked in.
     small   Exclude superfluous drivers, building a minimal system.

- ALLOC_SCHEME: Choose the memory allocation scheme of the kernel.
     standard    General-purpose allocation that supports freeing memory.
     alloconly   More efficient allocator but unable to free.

- ADAFLAGS, ASMFLAGS, and LDFLAGS, for the flags used by each tool
  respectively.

A shell script called 'install.sh' is provided for installing the resulting
binaries and generating the project's documentation in PDF and Info formats.

Several flags and environment variables are available for 'install.sh':

- DESTDIR and PREFIX.
- Pass 'strip' as the only argument for stripped binaries.

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

-- 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.
