pagetop_build/lib.rs
1/*!
2<div align="center">
3
4<h1>PageTop Build</h1>
5
6<p>Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto <strong>PageTop</strong>.</p>
7
8[](#-licencia)
9[](https://docs.rs/pagetop-build)
10[](https://crates.io/crates/pagetop-build)
11[](https://crates.io/crates/pagetop-build)
12
13</div>
14
15## Sobre PageTop
16
17[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
18clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
19configurables, basadas en HTML, CSS y JavaScript.
20
21
22# ⚡️ Guía rápida
23
24Añadir en el archivo `Cargo.toml` del proyecto:
25
26```toml
27[build-dependencies]
28pagetop-build = { ... }
29```
30
31Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
32archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
33
34## Incluir archivos estáticos desde un directorio
35
36Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
37ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
38
39```rust,no_run
40use pagetop_build::StaticFilesBundle;
41
42fn main() -> std::io::Result<()> {
43 StaticFilesBundle::from_dir("./static", None)
44 .with_name("guides")
45 .build()
46}
47```
48
49Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por
50ejemplo:
51
52```rust,no_run
53use pagetop_build::StaticFilesBundle;
54use std::path::Path;
55
56fn main() -> std::io::Result<()> {
57 fn only_pdf_files(path: &Path) -> bool {
58 // Selecciona únicamente los archivos con extensión `.pdf`.
59 path.extension().map_or(false, |ext| ext == "pdf")
60 }
61
62 StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
63 .with_name("guides")
64 .build()
65}
66```
67
68## Compilar archivos SCSS a CSS
69
70Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con
71el archivo CSS minificado obtenido. Por ejemplo:
72
73```rust,no_run
74use pagetop_build::StaticFilesBundle;
75
76fn main() -> std::io::Result<()> {
77 StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
78 .with_name("main_styles")
79 .build()
80}
81```
82
83Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso
84llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
85
86
87# 📦 Archivos generados
88
89Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
90[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
91donde se incluye el código necesario para compilar el proyecto. Por ejemplo, para
92`with_name("guides")` se genera un archivo llamado `guides.rs`.
93
94No hay ningún problema en generar más de un conjunto de recursos para cada proyecto siempre que se
95usen nombres diferentes.
96
97Normalmente no habrá que acceder a estos módulos; sólo declarar el nombre del conjunto de recursos
98en [`static_files_service!`](https://docs.rs/pagetop/latest/pagetop/macro.static_files_service.html)
99para configurar un servicio web que sirva los archivos desde la ruta indicada. Por ejemplo:
100
101```rust,ignore
102use pagetop::prelude::*;
103
104pub struct MyExtension;
105
106impl Extension for MyExtension {
107 // Servicio web que publica los recursos de `guides` en `/ruta/a/guides`.
108 fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
109 static_files_service!(scfg, guides => "/ruta/a/guides");
110 }
111}
112```
113*/
114
115#![doc(
116 html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
117)]
118
119use grass::{from_path, Options, OutputStyle};
120use pagetop_statics::{resource_dir, ResourceDir};
121
122use std::fs::{create_dir_all, remove_dir_all, File};
123use std::io::Write;
124use std::path::Path;
125
126/// Prepara un conjunto de recursos para ser incluidos en el binario del proyecto.
127pub struct StaticFilesBundle {
128 resource_dir: ResourceDir,
129}
130
131impl StaticFilesBundle {
132 /// Prepara el conjunto de recursos con los archivos de un directorio. Opcionalmente se puede
133 /// aplicar un filtro para seleccionar un subconjunto de los archivos.
134 ///
135 /// # Argumentos
136 ///
137 /// * `dir` - Directorio que contiene los archivos.
138 /// * `filter` - Una función opcional para aceptar o no un archivo según su ruta.
139 ///
140 /// # Ejemplo
141 ///
142 /// ```rust,no_run
143 /// use pagetop_build::StaticFilesBundle;
144 /// use std::path::Path;
145 ///
146 /// fn main() -> std::io::Result<()> {
147 /// fn only_images(path: &Path) -> bool {
148 /// matches!(
149 /// path.extension().and_then(|ext| ext.to_str()),
150 /// Some("jpg" | "png" | "gif")
151 /// )
152 /// }
153 ///
154 /// StaticFilesBundle::from_dir("./static", Some(only_images))
155 /// .with_name("images")
156 /// .build()
157 /// }
158 /// ```
159 pub fn from_dir<P>(dir: P, filter: Option<fn(&Path) -> bool>) -> Self
160 where
161 P: AsRef<Path>,
162 {
163 let dir_path = dir.as_ref();
164 let dir_str = dir_path.to_str().unwrap_or_else(|| {
165 panic!(
166 "Resource directory path is not valid UTF-8: {}",
167 dir_path.display()
168 );
169 });
170
171 let mut resource_dir = resource_dir(dir_str);
172
173 // Aplica el filtro si está definido.
174 if let Some(f) = filter {
175 resource_dir.with_filter(f);
176 }
177
178 // Identifica el directorio temporal de recursos.
179 StaticFilesBundle { resource_dir }
180 }
181
182 /// Prepara un recurso CSS minimizado a partir de la compilación de un archivo SCSS (que puede a
183 /// su vez importar otros archivos SCSS).
184 ///
185 /// # Argumentos
186 ///
187 /// * `path` - Archivo SCSS a compilar.
188 /// * `target_name` - Nombre para el archivo CSS.
189 ///
190 /// # Ejemplo
191 ///
192 /// ```rust,no_run
193 /// use pagetop_build::StaticFilesBundle;
194 ///
195 /// fn main() -> std::io::Result<()> {
196 /// StaticFilesBundle::from_scss("./bootstrap/scss/main.scss", "bootstrap.min.css")
197 /// .with_name("bootstrap_css")
198 /// .build()
199 /// }
200 /// ```
201 pub fn from_scss<P>(path: P, target_name: &str) -> Self
202 where
203 P: AsRef<Path>,
204 {
205 // Crea un directorio temporal para el archivo CSS.
206 let out_dir = std::env::var("OUT_DIR").unwrap();
207 let temp_dir = Path::new(&out_dir).join("from_scss_files");
208
209 // Limpia el directorio temporal de ejecuciones previas, si existe.
210 if temp_dir.exists() {
211 remove_dir_all(&temp_dir).unwrap_or_else(|e| {
212 panic!(
213 "Failed to clean temporary directory `{}`: {e}",
214 temp_dir.display()
215 );
216 });
217 }
218 create_dir_all(&temp_dir).unwrap_or_else(|e| {
219 panic!(
220 "Failed to create temporary directory `{}`: {e}",
221 temp_dir.display()
222 );
223 });
224
225 // Compila SCSS a CSS.
226 let css_content = from_path(
227 path.as_ref(),
228 &Options::default().style(OutputStyle::Compressed),
229 )
230 .unwrap_or_else(|e| {
231 panic!(
232 "Failed to compile SCSS file `{}`: {e}",
233 path.as_ref().display(),
234 )
235 });
236
237 // Guarda el archivo CSS compilado en el directorio temporal.
238 let css_path = temp_dir.join(target_name);
239 File::create(&css_path)
240 .unwrap_or_else(|_| panic!("Failed to create CSS file `{}`", css_path.display()))
241 .write_all(css_content.as_bytes())
242 .unwrap_or_else(|_| panic!("Failed to write CSS content to `{}`", css_path.display()));
243
244 // Identifica el directorio temporal de recursos.
245 StaticFilesBundle {
246 resource_dir: resource_dir(temp_dir.to_str().unwrap()),
247 }
248 }
249
250 /// Asigna un nombre al conjunto de recursos.
251 pub fn with_name(mut self, name: impl AsRef<str>) -> Self {
252 let name = name.as_ref();
253 let out_dir = std::env::var("OUT_DIR").unwrap();
254 let filename = Path::new(&out_dir).join(format!("{name}.rs"));
255 self.resource_dir.with_generated_filename(filename);
256 self.resource_dir.with_module_name(format!("bundle_{name}"));
257 self.resource_dir.with_generated_fn(name);
258 self
259 }
260
261 /// Contruye finalmente el conjunto de recursos para incluir en el binario de la aplicación.
262 pub fn build(self) -> std::io::Result<()> {
263 self.resource_dir.build()
264 }
265}