hilbert os is a 64-bit hobby operating system, which is not very mature yet. to
build and test it, you will need some software installed. on debian, i believe
the packages listed below are sufficient.

  - bison
  - flex
  - g++
  - gdb
  - git
  - libgmp-dev
  - libmpfr-dev
  - libmpc-dev
  - make
  - nasm
  - qemu-system-x86
  - texinfo
  - xorriso

next, you will need to download and compile some dependencies. the script in
setup.sh will do this for you. if it sees an environment variables MAKEOPTS, it
will pass the contents of that as arguments to invocations of make. otherwise,
it defaults to "-j$(nproc)".

now that we have all the dependencies, just run "make". the default target is
build/disk.iso, a bios-bootable disk image. you can run "make debug" to start
qemu with that disk, and attach gdb to it. you will have to run "continue" (or
"c" for short) in gdb to let qemu start. consider temporarily changing -O3 to
-Og in the CC_EXTRA_ARGS variable of the makefile temporarily if you want to
do any serious debugging.

acknowledgements (any under "dependencies" are downloaded during build):

  - dependencies/binutils (gnu binutils v2.42)
      copyright 2024 free software foundation, inc.
      license: dependencies/binutils/COPYING (gnu gpl v2)
      homepage: https://www.gnu.org/software/binutils/

  - dependencies/gcc (gnu compiler collection v14.1.0)
      copyright 2024 free software foundation, inc.
      license:
        dependencies/gcc/COPYING3 (gnu gpl v3)
        dependencies/gcc/COPYING.RUNTIME (gcc runtime library exception v3.1)
      homepage: https://gcc.gnu.org/
      i patch the output <memory> header file from libstdc++ with
        patches/gcc-memory.patch to include my std::allocator implementation.

  - dependencies/limine (limine bootloader v7.5.1)
      copyright 2019 - 2024 mintsuki and contributors
      license: dependencies/limine/COPYING (bsd two-clause)
      homepage: https://limine-bootloader.org/

  - dependencies/minstuki-headers
      copyright 2022 - 2024 mintsuki and contributors
      license: dependencies/mintsuki-headers/LICENSE (bsd zero-clause)
      homepage: https://github.com/osdev0/freestanding-headers/
      i patch the <stddef.h> header file with patches/minstuki-stddef.patch
        to add a max_align_t type to make libstdc++ happy. i use the commit
        dd3abd2d7147efc4170dff478d3b7730bed14147 so i don't have to worry
        about that file changing in a future commit.

  - skeleton/assets/burden.ppm
      ("selective focus photography snowflakes" by aaron burden)
      license: https://unsplash.com/license
      source: https://unsplash.com/photos/selective-focus-photography-snowflakes-9yhy1FXlKwI

  - skeleton/assets/terminus/*.psf (terminus font)
      copyright 2020 dimitar toshkov zhekov
      license: skeleton/assets/terminus-ofl.txt (sil open font license v1.1)
      homepage: https://terminus-font.sourceforge.net/

the following directories and files are copyright 2024 benji dial, under the
license in isc.txt (isc license):

  - applications
  - euler
  - kernel
  - libraries
  - makefile

the following file are released under the text in 0bsd.txt (zero-clause bsd):

  - clean-setup.sh
  - makefile
  - setup.sh

the following directories and files are released under the text in cc0.txt
(creative commons cc0 1.0 universal public domain dedication):

  - documentation
  - skeleton/assets/pointer.ppm

project structure:

  - applications/clock:
      a simple application that displays the current time in EDT.

  - applications/goldman:
      the default compositor.

  - applications/init:
      the initial program loaded by the kernel. currently it just starts the
      compositor and the clock, but in the future it will read some kind of
      configuration file and decide what to do based on that.

  - documentation:
      documentation. currently this directory is a bit disorganized, and has
      some descriptions of things that have not been created yet.

  - euler:
      (a minimal start to) a c++20 standard library, plus some hilbert
      specific functions. this uses the freestanding part of libstdc++.

  - kernel:
      the kernel.

  - libraries/daguerre:
      an image loading / rendering library.

  - libraries/pake:
      a widget library for windowed applications

  - patches:
      a couple patches that are applied to dependencies

  - skeleton:
      files that are copied directly to the initfs.