Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
this is a WIP PR that aims to simplify the way we simplify dune files. The idea is to separate the "static" files that are generated from the
mirage
tool from the project-specific files that are generated fromconfig.exe
. Here a high-level description of the new target workflow:Mirage Compilation Process
This document details the details of the compilation process for MirageOS unikernels.
It outlines the steps required to prepare, compile, and manage dependencies for Mirage applications.
Overview of the Compilation Process
Developing a simple application with Mirage involves starting with two primary files:
config.ml
: Contains the configuration of your unikernel.unikernel.ml
: The main application code.The usual workflow to configure and compile an unikernel is to run the following commands:
While hidden to the end-user,
mirage configure
is actually split into several lower-level key steps, described below.Configuration
Step 1: Initial Configuration
Executing
mirage configure --init-config
generates the essential scaffolding needed for compiling and executingconfig.exe
. This process creates the following files, if they don't already exist:These files are generic and independent of the specific content within
config.ml
. Their primary role is to enable the compilation ofconfig.exe
, which provides a runnable description of the unikernel. For example:For additional options and details, see the output of
./config.exe --help
. Theconfig.exe
binary drives the remaining setup process.Step 2: Persisting CLI options
The
mirage
command-line tool supports multiple sub-commands, designed to be used in a specific sequence. For example:In this workflow, users expect that
mirage describe
will detail the unikernel as configured, not in its generic form. Similarly,mirage clean
should remove all files generated during the configuration step. This implies that the CLI maintains state across invocations by remembering the options passed tomirage configure
. To do this,mirage configure <options>
records the specified options in a.mirage
file.Step 3: Library Initialization
The command
mirage configure --init-lib
lays down the scaffolding necessary for compiling the unikernel functor as a library. This action is also achievable by running./config.exe configure --init-lib
.This step modifies the existing
dune
file with specific rules to compile the provided functor as a library. The output is an OCaml library with the same name as the unikernel defined inconfig.ml
.Step 4: Application Configuration
Running
mirage configure --init-app ...
with the desired CLI options configures the final application. This can also be done through./config.exe configure --init-app ...
.This generates a new
mirage
directory, containing all files required to compile and package the application:Notes: Generated Files and Overwrite Rules
If a generated file already exists, its potential overwriting follows these rules:
;; generated by mirage <version>
will be overwritten.The
mirage clean
command also uses these rules to determine which files to delete or retain. Files marked as generated are removed, while others are left untouched. If you wish to edit and preserve any generated file, ensure to remove the "generated by" header.Notes: Using PPX or Libraries in
config.ml
To use PPX extensions or libraries within
config.ml
, first editdune.config
by removing the "generated by" header. Then, customize the compilation rules as needed.Dependency Management
Managing Lock Files
Generated dune files include an alias for creating lock files, which are crucial for packaging: execute
dune build @lock
(ormake lock
)During development, it could be beneficial to have a single lock file for all the unikernels in the repository. Use
make dev-lock
to create one such file.Pulling Dependencies
An alias in the generated dune files allows for pulling dependencies into a local
duniverse
folder: rundune build @pull
(ormake pull
).During development, it could be useful to pull all dependencies of all the unikernels. Use
dune build @dev-pull
ormake dev-pull
to achieve this.Pulling External Dependencies
TODO