# 🔓 LIBerate - Set Your Code Free!
**Source**: `cargo-mate/captain/src/cmd/liberate.rs` and `cargo-mate/captain/src/cmd/smune.rs:Commands::Liberate`
LIBerate is a powerful command that automatically generates a `lib.rs` file by scanning all Rust source files in your project and extracting all public items (structs, enums, functions, constants, types, traits, statics, unions, and impl blocks).
## Overview
**Main Handler**: `liberate.rs:handle_liberate()` (verified in `liberate.rs:224-336`)
LIBerate recursively walks through your project directory, parses all `.rs` files, and generates a comprehensive `lib.rs` file that:
- Declares all modules found in your project
- Re-exports all public items for easy access
- Organizes exports by category with helpful comments
- Handles errors gracefully with informative warnings
## Usage
### Basic Usage
```bash
# Scan current directory and generate .LIBerate-[timestamp].rs
cm liberate
# Scan a specific directory
cm liberate -t ./src
# Specify output file
cm liberate -o lib.rs
# Both target and output options
cm liberate -t ./src -o lib.rs
```
### Command Options
- `-t, --target <PATH>`: Target directory to scan (default: `.`)
- `-o, --out <PATH>`: Output file path (default: `.LIBerate-[timestamp].rs`)
## What It Does
**Implementation** (verified in `liberate.rs:224-336`):
1. **Recursive Scanning**: Uses `WalkDir` to walk through all subdirectories in the target path
2. **File Parsing**: Uses Rust's `syn` crate to parse each `.rs` file via `extract_exports_from_file()`
3. **Item Extraction**: Extracts all public items:
- Structs (`pub struct`)
- Enums (`pub enum`)
- Functions (`pub fn`)
- Constants (`pub const`)
- Type aliases (`pub type`)
- Traits (`pub trait`)
- Static variables (`pub static`)
- Unions (`pub union`)
- Impl blocks (for trait implementations)
4. **Module Generation**: Creates module declarations for each file
5. **Re-export Generation**: Generates `pub use` statements for all public items
## Generated Output
The generated `lib.rs` file will look like this:
```rust
//! Auto-generated lib.rs file
//! Generated by Cargo Mate LIBerate command
//! This file exports all public items from the project
pub mod module1;
pub mod module2;
pub mod utils;
// Re-export all public items
// Re-export from module1
pub use crate::module1::MyStruct;
pub use crate::module1::my_function;
pub use crate::module1::MyEnum;
// Re-export from module2
pub use crate::module2::AnotherStruct;
pub use crate::module2::helper_function;
// Re-export from utils
pub use crate::utils::UtilityType;
pub use crate::utils::CONSTANT_VALUE;
```
## Features
### Smart Filtering
- Automatically skips `lib.rs` and `main.rs` to avoid circular references
- Skips files starting with `.LIBerate-` to avoid scanning its own output
- Only includes public items (items marked with `pub`)
### Error Handling
- Gracefully handles parse errors with informative warnings
- Continues processing even if some files fail to parse
- Provides statistics on files scanned, modules found, and errors encountered
### Module Merging
- If multiple files have the same module name (based on file stem), exports are merged
- Useful for projects with multiple files that should be treated as one module
## Examples
### Example 1: Generate lib.rs for Current Project
```bash
cm liberate -t ./src -o src/lib.rs
```
This will:
1. Scan all `.rs` files in `./src` and subdirectories
2. Extract all public items
3. Generate `src/lib.rs` with module declarations and re-exports
### Example 2: Preview Generated File
```bash
cm liberate -t ./src -o preview-lib.rs
cat preview-lib.rs
```
Generate to a preview file first, review it, then copy to `src/lib.rs` if satisfied.
### Example 3: Scan Specific Subdirectory
```bash
cm liberate -t ./src/utils -o utils-lib.rs
```
Generate a lib.rs for just the utils subdirectory.
## Output Statistics
After scanning, LIBerate displays:
- **Files scanned**: Total number of `.rs` files found
- **Modules found**: Number of unique modules with public items
- **Errors**: Number of files that failed to parse (with details)
Example output:
```
🔓 LIBerate - Setting your code free!
📂 Scanning directory: ./src
📝 Output file: .LIBerate-20241201_143022.rs
📊 Statistics:
Files scanned: 15
Modules found: 12
Errors: 0
🔨 Generating lib.rs...
✅ Successfully generated lib.rs!
Location: .LIBerate-20241201_143022.rs
💡 Next steps:
1. Review the generated file
2. Copy it to your src/lib.rs if needed
3. Adjust module paths as necessary
```
## Limitations
1. **Module Structure**: LIBerate uses the file stem (filename without extension) as the module name. For nested modules, you may need to adjust the generated file to match Rust's module system requirements.
2. **Inline Modules**: Inline modules (modules defined with `mod { ... }`) are partially supported - items within inline modules are extracted, but the module structure may need manual adjustment.
3. **Macros**: Public macros are not currently extracted (this is a limitation of the current implementation).
4. **File Structure**: The generated `lib.rs` assumes files are in a flat structure or that you'll manually adjust module paths for nested directories.
## Tips
1. **Review Before Using**: Always review the generated file before replacing your existing `lib.rs`
2. **Incremental Approach**: Start with a subdirectory to see how it works
3. **Backup First**: Make a backup of your existing `lib.rs` if you have one
4. **Customize**: The generated file is a starting point - customize it to fit your project's needs
## Integration
LIBerate is integrated with Cargo Mate's license system and requires a valid license to use. It follows the same patterns as other Cargo Mate commands for consistency.
## See Also
- `cm help` - General Cargo Mate help
- `cm deps` - Analyze dependencies
- `cm map` - Visualize dependency maps
---
**Note**: This command is inspired by Python's `__init__.py` generation patterns, adapted for Rust's module system. It helps "liberate" your code by making all public items easily accessible from a single entry point.