diff --git a/content/4.cargo/2.modules.md b/content/4.cargo/2.modules.md new file mode 100644 index 0000000..62289fc --- /dev/null +++ b/content/4.cargo/2.modules.md @@ -0,0 +1,257 @@ +--- +title: 'Cargo' +description: '' +draft: true +data: + type: 'custom' + topicLevel: 'start' + position: + x: 200 + y: 750 + sourcePosition: + error-handling: 'right' + targetPosition: + traits: 'bottom' +--- +# Organizando Proyectos en Rust: Módulos y Visibilidad + +Cuando desarrollamos en Rust, mantener el código organizado es esencial para la escalabilidad y la mantenibilidad. Rust ofrece un sistema de módulos flexible que nos ayuda a dividir el código en componentes más manejables. En este artículo exploraremos cómo crear y gestionar módulos, controlar su visibilidad, y estructurar proyectos de manera eficiente, abordando las prácticas más recomendadas en la comunidad. + +--- + +## Introducción a los módulos + +Los módulos en Rust agrupan código relacionado bajo un espacio de nombres, permitiendo: + +- **Organización lógica:** Divide el código en archivos o directorios. +- **Encapsulación:** Restringe qué partes del código son accesibles externamente. +- **Reutilización:** Facilita la modularidad y el uso compartido de código. + +Un módulo puede contener funciones, estructuras, enumeraciones, constantes e incluso otros módulos. + +--- + +## Crear y gestionar módulos + +### Módulos en el mismo archivo +La forma más sencilla de declarar un módulo es hacerlo directamente en el archivo: + +```rust +mod math { + pub fn add(a: i32, b: i32) -> i32 { + a + b + } +} +``` + +Luego accedes a los elementos públicos con el prefijo del módulo: +```rust +fn main() { + let sum = math::add(2, 3); + println!("Suma: {}", sum); +} +``` + +### Módulos en archivos separados +Para mantener el código limpio, puedes mover los módulos a archivos independientes: + +En `main.rs`: +```rust +mod math; + +fn main() { + let sum = math::add(5, 7); + println!("Suma: {}", sum); +} +``` + +En `math.rs`: +```rust +pub fn add(a: i32, b: i32) -> i32 { + a + b +} +``` + +### Módulos como directorios +Si un módulo incluye submódulos, puedes organizarlo en un directorio con un archivo `mod.rs` o estructurarlo usando archivos con el mismo nombre que los submódulos. + +Estructura de ejemplo: +``` +src/ +├── main.rs +├── math/ +│ ├── mod.rs +│ ├── add.rs +│ └── multiply.rs +``` + +En `math/mod.rs`: +```rust +pub mod add; +pub mod multiply; +``` + +--- + +## Control de visibilidad + +Por defecto, los módulos y sus elementos son privados. Para hacerlos accesibles, usa `pub`. + +```rust +mod shapes { + pub struct Rectangle { + pub width: u32, + pub height: u32, + } + + impl Rectangle { + pub fn area(&self) -> u32 { + self.width * self.height + } + } +} +``` + +El acceso desde otro módulo o función será así: +```rust +fn main() { + let rect = shapes::Rectangle { width: 10, height: 20 }; + println!("Área: {}", rect.area()); +} +``` + +--- + +## Estructuración recomendada para proyectos Rust + +La organización de un proyecto depende de su propósito. Aquí hay patrones comunes: + +### 1. **Proyectos ejecutables simples** +Los proyectos pequeños suelen tener un único archivo `main.rs`: + +``` +src/ +└── main.rs +``` + +### 2. **Proyectos ejecutables grandes** +A medida que crece, puedes mover lógica a módulos: + +``` +src/ +├── main.rs +├── config.rs +├── handlers.rs +└── utils.rs +``` + +En `main.rs`: +```rust +mod config; +mod handlers; +mod utils; +``` + +### 3. **Bibliotecas** +Las bibliotecas usan un archivo `lib.rs` para exponer su API pública: + +``` +src/ +├── lib.rs +└── utils.rs +``` + +En `lib.rs`: +```rust +pub mod utils; +``` + +### 4. **Híbridos (ejecutable + biblioteca)** +Un proyecto puede tener `main.rs` para la aplicación y `lib.rs` para lógica reutilizable: + +``` +src/ +├── lib.rs +└── main.rs +``` + +En `main.rs`: +```rust +use mycrate::utils::some_function; + +fn main() { + some_function(); +} +``` + +En `lib.rs`: +```rust +pub mod utils { + pub fn some_function() { + println!("Función compartida"); + } +} +``` + +### 5. **Proyectos con múltiples binarios** +Usa un directorio `src/bin/` para incluir otros ejecutables: + +``` +src/ +├── main.rs +├── lib.rs +└── bin/ + ├── tool1.rs + └── tool2.rs +``` + +--- + +## Puntos de entrada: `main.rs` y `lib.rs` + +### `main.rs` +Es el punto de entrada de los ejecutables. Aquí defines la lógica inicial de tu programa. + +### `lib.rs` +Sirve como punto de entrada para bibliotecas. Aquí defines qué módulos y funciones serán públicos para los usuarios de la biblioteca. + +### Coexistencia de `main.rs` y `lib.rs` +En proyectos híbridos, `lib.rs` puede contener la lógica principal reutilizable y `main.rs` consumirla: + +En `lib.rs`: +```rust +pub fn greet(name: &str) { + println!("Hola, {}!", name); +} +``` + +En `main.rs`: +```rust +use mycrate::greet; + +fn main() { + greet("Mundo"); +} +``` + +--- + +## Buenas prácticas y convenciones + +1. **Divide y vencerás:** Usa módulos para separar responsabilidades. +2. **Restricción de visibilidad:** Haz públicos solo los elementos necesarios. +3. **Nombres consistentes:** Usa nombres descriptivos para módulos y archivos. +4. **Centraliza lo común:** Mueve funciones reutilizables a `lib.rs`. + +--- + +## Configuraciones adicionales para módulos + +- **Agrupación lógica:** Usa directorios para módulos con múltiples submódulos. +- **Macros compartidas:** Crea un módulo separado para macros reutilizables, por ejemplo, `src/macros.rs`. + +--- + +## Conclusión + +Organizar proyectos con módulos en Rust no solo mejora la claridad del código, sino que también facilita su escalabilidad. Ya sea que trabajes en un ejecutable, una biblioteca o ambos, seguir estas prácticas te ayudará a mantener un código limpio, reutilizable y fácil de entender. ¡Experimenta con estas técnicas y lleva tus proyectos al siguiente nivel! 🚀