How kojix2/minimap2-cr works
Purpose and public entry point
minimap2-cr is a Crystal shard exposing in-process bindings to the minimap2 long-read mapper. Consumers load src/minimap2.cr, construct a Minimap2::Aligner, load a FASTA-backed reference index, and map query sequences without invoking the minimap2 CLI.
Paths: src/minimap2.cr, src/minimap2/aligner.cr
Native dependency lifecycle
The shard vendors/builds minimap2 during dependency installation through its postinstall configuration. ext/build.cr is the native build boundary: it produces the minimap2 library consumed by Crystal FFI. Linux builds require a C toolchain and zlib headers; runtime library discovery may require LD_LIBRARY_PATH pointing at ext.
Paths: shard.yml, ext/build.cr, src/minimap2/ffi.cr
FFI boundary
Minimap2::LibMinimap2 declares bindings to minimap2’s C API, including native structures, constants, flags, index operations, and mapping calls. This file is the ABI-sensitive boundary: Crystal code should translate inputs/options before crossing it and convert native results immediately after return.
Paths: src/minimap2/ffi.cr, src/minimap2/types.cr
Aligner lifecycle and mapping flow
Minimap2::Aligner owns the loaded native reference/index and configured mapping options. Construction follows either the convenience initializer or builder pipeline; mapping accepts a query plus high-level tag toggles (cs, md, ds) and optional raw minimap2 flags. It invokes native mapping and returns Crystal mapping records. The aligner also provides indexed reference subsequence access via seq(name, start, stop).
Paths: src/minimap2/aligner.cr, src/minimap2/types.cr
Configuration and builder stage
Minimap2::Builder is the explicit configuration layer. It selects minimap2 presets (such as ONT, HiFi, splice, assembly, and short-read modes), enables output behavior such as CIGAR generation, sets indexing threads, and loads a reference path. It materializes an Aligner, separating option assembly from native index creation.
Paths: src/minimap2/builder.cr, src/minimap2/aligner.cr
Data model and sequence utilities
Crystal-facing result and option types encapsulate mapping outputs, including coordinates, alignment metadata, and requested cs/MD/ds tag fields. Sequence-oriented utilities provide operations such as reverse complement independently of the native mapper.
Paths: src/minimap2/types.cr, src/minimap2/seq_util.cr
Validation and usage shape
The primary integration contract is demonstrated by mapping fixture/query sequences against FASTA input and asserting returned alignments. The example shows intended library embedding: configure once, then issue repeated map calls against the loaded index.
Paths: spec/minimap2_spec.cr, spec/fixtures/test_data.fasta, examples/aligner_example.cr
Main entry points: aligner.cr Aligner · builder.cr Builder · types.cr Crystal types · minimap2.cr minimap2 entry point
Components 12
Crystal API
Public library surface and mapping workflow.
- minimap2 entry point · Public shard entry point.
src/minimap2.cr - Builder · Assembles presets, options, threads, and reference input.
src/minimap2/builder.cr - Aligner · Owns the native index and exposes map and seq.
src/minimap2/aligner.cr - Crystal types · Options and Crystal-facing mapping records.
src/minimap2/types.cr - Sequence utilities · Provides Crystal-side operations such as reverse complement.
src/minimap2/seq_util.cr
Native integration
Vendored minimap2 build and ABI boundary.
- LibMinimap2 FFI · ABI-sensitive native declarations, flags, structures, and calls.
src/minimap2/ffi.cr - Native build · Builds the vendored minimap2 library.
ext/build.cr - Shard configuration · Triggers the native postinstall lifecycle.
shard.yml - minimap2 library · Built C library loaded by Crystal FFI.
Other components
- FASTA reference · Loaded to create the native reference index.
spec/fixtures/test_data.fasta - Embedding example · Configure once and issue repeated map calls.
examples/aligner_example.cr - Integration spec · Maps fixture queries and asserts returned alignments.
spec/minimap2_spec.cr
Connections 16
- minimap2 entry point → Builder: exposes
- minimap2 entry point → Aligner: exposes
- minimap2 entry point → Crystal types: loads
- Builder → Aligner: materializes
- Builder → Crystal types: assembles options
- Builder → FASTA reference: loads reference path
- Aligner → Crystal types: accepts options and returns records
- Aligner → LibMinimap2 FFI: creates index and maps
- Sequence utilities → Crystal types: supports sequences
- LibMinimap2 FFI → minimap2 library: calls C API
- Shard configuration → Native build: postinstall invokes
- Native build → minimap2 library: produces
- Embedding example → Builder: configures
- Embedding example → Aligner: repeated map calls
- Integration spec → Aligner: validates mapping
- Integration spec → FASTA reference: uses fixture