How vigna/fastutil works
Main Components
• Core Library Components: Represent the core data structures (lists, maps, sets, queues, etc.) and algorithms that fastutil provides. You might group these by type (e.g., “Primitive Collections,” “Object Collections” and “Big Arrays/Lists”).
• Driver/Preprocessor Module: Show the “drv” directory and related scripts (like gencsource.sh) that generate the Java sources. This is a critical subsystem because fastutil uses a C preprocessor to customize and generate its source code.
• Build and Packaging Infrastructure: Illustrate the build tools and scripts (Ant’s build.xml, makefile, Ivy’s ivy.xml, Maven POM files, bnd scripts) which collectively manage compiling, testing, and packaging into different jars (fastutil-core.jar and fastutil.jar). Also include the split.sh script used for creating the two jar distributions.
• Testing Suite: Include the “test” directory as a distinct component, highlighting unit tests for the various data structures and utilities provided by the library.
• Integration/Examples and Additional Artifacts: Optionally, highlight the “guava” tests and any integration tests in the “src/it” directory that demonstrate interoperability with other libraries.
• Link the Testing Suite to the Core Library to denote that tests validate the performance and correctness of all data structures and algorithms.
Architectural Patterns and Design Principles
• The separation-of-concerns is clearly visible—the library code is generated separately from the driver (code generation) and then built and packaged using a well-defined build system.
• Modular design: fastutil splits its distribution into two jars so that its “core” functionalities and additional utilities are separated for convenience in dependency management.
• Use of code generation via conditional compilation: this can be shown as a pre-build stage that produces the optimized, type-specific Java code from more generic drivers.
Relevant Technologies and Tools
• Java: The programming language and runtime.
• Apache Ant / Maven / Ivy: For building, dependency management, and packaging.
• Bnd: For OSGi packaging of components.
• Shell Scripts (gencsource.sh, split.sh, find-deps.sh): For code generation and dependency analysis.
• JUnit (and Hamcrest): For unit testing.
• JDeps: As noted in the README, used in the dependency analysis for generating a custom jar.