Project Files
Cryptol supports specifying a project file that can accelerate the repeated loading and testing of a large, interconnected set of source files. Cryptol will remember the hashes of the files previously checked and use this to avoid type-checking and testing files that are unchanged since the previous loading of the project.
To use this feature a cryproject.toml should be created in the root
directory of the cryptol source files that lists all of the top-level
modules of the project. The dependencies of these modules will implicitly
be added to the project.
To check a whole project, Cryptol can be invoked with the --project
or -p flag using the directory containing the project as an
argument. This will type-check all of the modules in the project and
check the docstrings for all modules in the project.
All errors are reported to stdout. When all modules load and all tests
pass cryptol’s exit code will be 0. When the project does not load
successfully the exit code is 1.
After loading a project the cache information is saved into a Cryptol-
managed file in the project root directory .cryproject/loadcache.toml.
Example:
cryptol -p myproject/
To discard the previous cached results and reload a whole project use
--refresh-project. This can be useful when versions of external
tools have changed or simply to get confidence that everything is still
in a working state.
Example:
cryptol -p myproject/ --refresh-project
cryproject.toml Format
Project files are described by a TOML file using the following top-level key-value assignments:
root- optional - string - can optionally be specified to override the directory that Cryptol files are located in. Otherwise modules are loaded relative to the directory containing thecryproject.toml.modules- required - list of strings - is a list of filenames containing the top-level modules in a project. These modules, and all of their dependencies, will be loaded when the project is loaded.
Example directory structure:
project
├── Id.c
├── Id.cry
├── Id.dylib
├── Main.cry
└── cryproject.toml
Example cryproject.toml:
modules = [
"Id.cry",
"Main.cry",
]
loadcache.toml Format
After loading a project a cache file is generated and stored in
.cryproject/loadcache.toml. This file contains a version number to
allow caches to automatically invalidate when the project subsystem
updates. Modules that fail to load at all are not listed in the cache
file and will be reprocessed on subsequent project loads even if unchanged.
version- integer - specifies the cache file format version in order to allow old caches to be invalidated when Cryptol changes the meaning of this file.file- string - specifies the absolute path to a Cryptol module for those stored in files.memory- string - specifies the module name of a primitive module built into Cryptol.fingerprint- string - specifies a SHA2-256 hash of the source file which is used to detect when the source file has changed from the previous run.foreign_fingerprints- list of string - is a list of SHA2-256 hashes of dynamic libraries that this Cryptol file directly loads.include_fingerprints- list of string - is a list of SHA2-256 hashes of pre-processor included files that this Cryptol files directly includes.docstring_result- boolean - istruewhen:check-docstringspreviously succeeded for this module andfalsewhen it previously failed. It will be missing if tests were never run on this module.
version = 1
[[modules]]
fingerprint = "2f671b21f2933a006b6a843c7f281388e6b8227f9944b111f87711dc9ca8448f"
foreign_fingerprints = []
include_fingerprints = []
memory = "Cryptol"
[[modules]]
docstring_result = true
file = "/path/to/project/Id.cry"
fingerprint = "a9e6f7a4b65ead6bd8e27442717d6b0dc54afc73e34b18c32f005ceb7a8f3c34"
foreign_fingerprints = [ "c7767a13281a56631c72b9b6f69a17746dc02213e7f2b24a8a4a6fe7afd9ee0a" ]
include_fingerprints = []
[[modules]]
docstring_result = true
file = "/path/to/project/Main.cry"
fingerprint = "6b36f965ebb1a68cf76d689a966806ec879540aa6576a76c1aaa7705a4af09d5"
foreign_fingerprints = []
include_fingerprints = []