From 8d0267f23b691d0ad15f2935076f5998052536f0 Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Thu, 11 Dec 2025 11:39:00 -0500 Subject: [PATCH] docs: redistribute faq content to relevant sections (fixes #39) --- docs/explanation/faq.md | 65 --------------------------- docs/explanation/index.md | 1 - docs/explanation/mode-of-operation.md | 16 +++++-- docs/explanation/slices.md | 8 +++- 4 files changed, 20 insertions(+), 70 deletions(-) delete mode 100644 docs/explanation/faq.md diff --git a/docs/explanation/faq.md b/docs/explanation/faq.md deleted file mode 100644 index 801e755..0000000 --- a/docs/explanation/faq.md +++ /dev/null @@ -1,65 +0,0 @@ -# FAQ - -This page lists some known limitations and frequently asked questions. - - -(faq_arbitrary_package_names)= - -## Is it possible to use arbitrary package names? - -No, package names must be the same as the package names in the archive, so that -there's a single namespace to remember and respect. - - -(faq_available_ubuntu_versions)= - -## Which Ubuntu versions have package slices? - -The slice definitions are located at the {{chisel_releases_repo}}. The -`ubuntu-XX.YY` branches in that repository contain the slice definitions for -the corresponding Ubuntu releases. - -If you find a specific release missing, let the maintainers know by [creating a -new issue] in the {{chisel_releases_repo}}. - - -(faq_non-ubuntu_archives)= - -## Is it possible to use non-Ubuntu archives? - -No. The supported archives are described at -{ref}`chisel_yaml_format_spec_archives`. - - -(faq_ppa)= - -## Is it possible to use PPAs? - -Not at the moment. - - -(faq_file_ownership_preserved)= - -## Is file ownership preserved? - -No, Chisel does not yet preserve the owner UID:GID of files extracted from -packages. The owner of the extracted files is the current user. - - -(faq_reproducible_output)= - -## Does Chisel support reproducible rootfs outputs? - -Chisel always fetches the latest version of a package from the archives. Thus, -the root file systems Chisel produces in subsequent executions may not be -identical if a package has changed in the meantime. - -Chisel also does not support pinning package versions. - -Related: [Issue 154]. - - - - -[creating a new issue]: https://github.com/canonical/chisel-releases/issues/new -[Issue 154]: https://github.com/canonical/chisel/issues/154 diff --git a/docs/explanation/index.md b/docs/explanation/index.md index d9e057a..ad132e0 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -7,5 +7,4 @@ This section of the documentation covers the core concepts of Chisel. mode-of-operation slices -faq ``` diff --git a/docs/explanation/mode-of-operation.md b/docs/explanation/mode-of-operation.md index 6fa067e..41f8210 100644 --- a/docs/explanation/mode-of-operation.md +++ b/docs/explanation/mode-of-operation.md @@ -29,7 +29,9 @@ Chisel uses the {{cut_cmd}} to _slice_ Ubuntu packages, as depicted in the workf Chisel fetches, reads and validates the {ref}`chisel-release`. This includes parsing the {ref}`chisel_yaml_ref` and {ref}`slice -definitions` while validating the release and checking for conflicting paths across packages. +definitions` while validating the release and checking for +conflicting paths across packages. Slice definitions for each Ubuntu release are +located in the corresponding `ubuntu-XX.YY` branch of the {{chisel_releases_repo}}. @@ -50,7 +52,14 @@ definitions` while validating the release and checking fo Chisel talks to the {ref}`chisel_yaml_format_spec_archives` directly. It fetches, validates and parses their `InRelease` files. It then resolves which archive holds the **requested** packages and fetches -the corresponding package tarballs. +the corresponding package tarballs. Chisel always fetches the latest version of +a package from the archives, and does not support pinning package versions. +Thus, the root file systems Chisel produces in subsequent executions may not be +identical if a package has changed in the meantime. + +The supported archives are described at +{ref}`chisel_yaml_format_spec_archives`; non-Ubuntu archives and PPAs are not +supported. @@ -69,7 +78,8 @@ the corresponding package tarballs. Chisel groups and merges all slice definitions per package. Then, for every package, it extracts the **specified slices' paths** into -the provided root file system. +the provided root file system. File ownership (UID:GID) is not preserved +during this process; the owner of all extracted files is set to the current user. diff --git a/docs/explanation/slices.md b/docs/explanation/slices.md index 99aabde..4aa1ef5 100644 --- a/docs/explanation/slices.md +++ b/docs/explanation/slices.md @@ -40,12 +40,18 @@ A package's slices can be defined via a YAML slice definitions file. Check ## Naming convention +### Slice naming + In Chisel, slices are recognized by the following pattern: `_`. For example, the slice `libc6_libs` refers to the slice definition `libs` of the package `libc6`. - The use of an underscore in this pattern is what distinguishes package names from slice names, as this character is not allowed in Debian package names. + +### Package naming + +Package names must be the same as the package names in the archive, so that +there's a single namespace to remember and respect.