Controlling Internal and External Visibility of holons crate modules #208
evomimic
started this conversation in
Design Discussions
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Managing Dependencies and Visibility in the
holons
CrateThis document outlines how to design the public API of the
holons
crate to hide its internal structure from external crates while preserving a clear and organized module hierarchy for internal use.Problem
The
holons
crate has a complex internal module hierarchy with multiple layers:holons_core
,holons_guest
,holons_init
holons_core
:core_shared_objects
,reference_layer
,utils
To avoid exposing this complexity to external crates, we need a way to:
Solution
1. Define the Public Interface
Create a top-level public module (
lib.rs
) to serve as the entry point for external users. Use this module to re-export the public parts of your internal modules.Example (
lib.rs
):2. Keep Internal Modules Private
Mark modules that are not part of the public API as
pub(crate)
or private (mod
). For example:3. Manage Internal Visibility
If modules need to interact with one another internally, use
pub(crate)
orpub(super)
to restrict visibility appropriately. This ensures that dependencies within the crate remain controlled and clear.4. Use a Prelude (Optional)
If there are common types, traits, or functions that external users need frequently, create a
prelude
module to simplify imports:5. Document the Public API
To make the crate more user-friendly, document the public API in lib.rs and other public-facing modules. This helps guide users on how to use your crate without needing to understand its internal structure.
Example: External Usage
With this setup, an external crate using
holons
will see a clean and intuitive API:Benefits of This Approach
holons
crate can access internal modules without restrictions, maintaining the 2nd and 3rd layer structure for internal use.Beta Was this translation helpful? Give feedback.
All reactions