dofigen_lib/
lib.rs

1//! # dofigen_lib
2//!
3//! `dofigen_lib` help creating Dockerfile with a simplified structure and made to cache the build with Buildkit.
4//! You also can parse the structure from YAML or JSON.
5//!
6//! ```
7//! use dofigen_lib::*;
8//! use pretty_assertions_sorted::assert_eq_sorted;
9//!
10//! let mut context = DofigenContext::new();
11//!
12//! let dofigen = context.parse_from_string(r#"
13//! fromImage:
14//!   path: ubuntu
15//! "#).unwrap();
16//!
17//! let dockerfile = generate_dockerfile(&dofigen).unwrap();
18//! ```
19
20mod context;
21mod deserialize;
22mod dockerfile_struct;
23mod dofigen_struct;
24mod errors;
25mod extend;
26#[cfg(feature = "permissive")]
27mod from_str;
28mod generator;
29#[cfg(feature = "json_schema")]
30mod json_schema;
31mod linter;
32pub mod lock;
33#[cfg(feature = "json_schema")]
34use schemars::gen::*;
35pub use {
36    context::*, deserialize::*, dofigen_struct::*, errors::*, extend::*,
37    generator::GenerationContext, linter::*,
38};
39
40#[cfg(all(feature = "strict", feature = "permissive"))]
41compile_error!("You can't enable both 'strict' and 'permissive' features at the same time.");
42
43pub(crate) const DOCKERFILE_VERSION: &str = "1.11";
44
45const FILE_HEADER_COMMENTS: [&str; 2] = [
46    concat!(
47        "This file is generated by Dofigen v",
48        env!("CARGO_PKG_VERSION")
49    ),
50    concat!("See ", env!("CARGO_PKG_REPOSITORY")),
51];
52
53/// Generates the Dockerfile content from a Dofigen struct.
54///
55/// # Examples
56///
57/// ```
58/// use dofigen_lib::*;
59/// use pretty_assertions_sorted::assert_eq_sorted;
60///
61/// let dofigen = Dofigen {
62///     stage: Stage {
63///         from: ImageName {
64///             path: String::from("ubuntu"),
65///             ..Default::default()
66///         }.into(),
67///         ..Default::default()
68///     },
69///     ..Default::default()
70/// };
71/// let dockerfile: String = generate_dockerfile(&dofigen).unwrap();
72/// assert_eq_sorted!(
73///     dockerfile,
74///     "# syntax=docker/dockerfile:1.11\n# This file is generated by Dofigen v0.0.0\n# See https://github.com/lenra-io/dofigen\n\n# runtime\nFROM ubuntu AS runtime\nUSER 1000:1000\n"
75/// );
76/// ```
77#[deprecated(
78    since = "2.2.0",
79    note = "Please use `GenerationContext::generate_dockerfile` from `dofigen_lib` instead"
80)]
81pub fn generate_dockerfile(dofigen: &Dofigen) -> Result<String> {
82    GenerationContext::from(dofigen.clone()).generate_dockerfile()
83}
84
85/// Generates the .dockerignore file content from an Dofigen struct.
86///
87/// # Examples
88///
89/// ## Define the build context
90///
91/// ```
92/// use dofigen_lib::*;
93/// use pretty_assertions_sorted::assert_eq_sorted;
94///
95/// let dofigen = Dofigen {
96///     context: vec![String::from("/src")].into(),
97///     ..Default::default()
98/// };
99/// let dockerfile: String = generate_dockerignore(&dofigen);
100/// assert_eq_sorted!(
101///     dockerfile,
102///     "# This file is generated by Dofigen v0.0.0\n# See https://github.com/lenra-io/dofigen\n\n**\n!/src\n"
103/// );
104/// ```
105///
106/// ## Ignore a path
107///
108/// ```
109/// use dofigen_lib::*;
110/// use pretty_assertions_sorted::assert_eq_sorted;
111///
112/// let dofigen = Dofigen {
113///     ignore: vec![String::from("target")].into(),
114///     ..Default::default()
115/// };
116/// let dockerfile: String = generate_dockerignore(&dofigen);
117/// assert_eq_sorted!(
118///     dockerfile,
119///     "# This file is generated by Dofigen v0.0.0\n# See https://github.com/lenra-io/dofigen\n\ntarget\n"
120/// );
121/// ```
122///
123/// ## Define context ignoring a specific files
124///
125/// ```
126/// use dofigen_lib::*;
127/// use pretty_assertions_sorted::assert_eq_sorted;
128///
129/// let dofigen = Dofigen {
130///     context: vec![String::from("/src")].into(),
131///     ignore: vec![String::from("/src/*.test.rs")].into(),
132///     ..Default::default()
133/// };
134/// let dockerfile: String = generate_dockerignore(&dofigen);
135/// assert_eq_sorted!(
136///     dockerfile,
137///     "# This file is generated by Dofigen v0.0.0\n# See https://github.com/lenra-io/dofigen\n\n**\n!/src\n/src/*.test.rs\n"
138/// );
139/// ```
140#[deprecated(
141    since = "2.2.0",
142    note = "Please use `GenerationContext::generate_dockerignore` from `dofigen_lib` instead"
143)]
144pub fn generate_dockerignore(dofigen: &Dofigen) -> String {
145    GenerationContext::from(dofigen.clone())
146        .generate_dockerignore()
147        .unwrap()
148}
149
150/// Generates the effective Dofigen content from a Dofigen struct.
151///
152/// # Examples
153///
154/// ```
155/// use dofigen_lib::*;
156/// use pretty_assertions_sorted::assert_eq_sorted;
157///
158/// let dofigen = Dofigen {
159///     stage: Stage {
160///         from: ImageName {
161///             path: String::from("ubuntu"),
162///             ..Default::default()
163///         }.into(),
164///         ..Default::default()
165///     },
166///     ..Default::default()
167/// };
168/// let dofigen: String = generate_effective_content(&dofigen).unwrap();
169/// assert_eq_sorted!(
170///     dofigen,
171///     "fromImage:\n  path: ubuntu\n"
172/// );
173/// ```
174pub fn generate_effective_content(dofigen: &Dofigen) -> Result<String> {
175    Ok(serde_yaml::to_string(&dofigen)?)
176}
177
178/// Generates the JSON schema for the Dofigen struct.
179/// This is useful to validate the structure and IDE autocompletion.
180#[cfg(feature = "json_schema")]
181pub fn generate_json_schema() -> String {
182    let settings = SchemaSettings::default().with(|s| {
183        s.option_nullable = true;
184        s.option_add_null_type = true;
185    });
186    let gen = settings.into_generator();
187    let schema = gen.into_root_schema_for::<Extend<DofigenPatch>>();
188    serde_json::to_string_pretty(&schema).unwrap()
189}