feat(Snapcraft): move parts lifecycle into a reference #163
Conversation
Sophie-Pages
force-pushed
the
feat/snapcraft-parts-lifecycle
branch
from
2cfb4e8 to
d8ae70b
Compare
Sophie-Pages
force-pushed
the
feat/snapcraft-parts-lifecycle
branch
3 times, most recently
from
f1b0922 to
9fc34e5
Compare
Streamline documentation and add links to the reference.
| Each plugin defines the default actions that happen during a step. This behavior can be changed in two ways. | ||
|
|
||
| - By using `override-<step-name>` in `snapcraft.yaml`. See [Overriding steps](/t/scriptlets/4892) for more details. | ||
| - By using a local plugin. This can inherit the parent plugin or scaffolding from the original. See [Local plugins](/t/writing-local-plugins/5125) for more details. |
There was a problem hiding this comment.
It may be prudent to mention that this hasn't been supported for recent bases in snaps for several years -- I believe the cut-off is core20?
| | `CRAFT_PART_SRC` | **`parts/<part-name>/src`** | the location of the source during the *pull* step | | ||
| | `CRAFT_PART_BUILD` | **`parts/<part-name>/build`** | the working directory during the *build* step | | ||
| | `CRAFT_PART_INSTALL`| **`parts/<part-name>/install`** | contains the results of the *build* step and the stage packages. | | ||
| | `CRAFT_STAGE` | **`stage`** | shared by all parts, this directory contains the development libraries, headers, and other components (e.g.; pkgconfig files) that need to be accessible from other parts | |
There was a problem hiding this comment.
"This directory can contain" -- it isn't necessary that they do so (depends on the plugin, stage:, the build script in the source itself, actions in override-build, etc.)
Likewise it definitely contains the contents of each part's CRAFT_PART_INSTALL sans any likewise shenanigans as above.
| * It can build snaps locally or send remote tasks to Launchpad. | ||
| * It allows the developer to register and log into the Snap Store. | ||
| * It can upload snaps to the Snap Store. | ||
| * It can promote snaps to different channels. |
There was a problem hiding this comment.
I would remove the "It" from these lines; it's well established we're talking about Snapcraft, and it better mirrors the previous lines (4-6).
|
|
||
| Snaps are created using a build recipe defined in a file called `snapcraft.yaml`. | ||
|
|
||
| When the snapcraft tool is executed on the command line, it will look for the file in the current project work directory, either in the top-level folder or a `snap` subdirectory. If the file is found, snapcraft will then parse its contents and progress the build toward completion. |
There was a problem hiding this comment.
@medubelko does snapcraft (plan to continue to) support build-aux/snap? Is it a recommended path?
|
|
||
| <h3 id='heading--definitions'>Main definitions inside snapcraft.yaml</h3> | ||
|
|
||
| There is no one way for how a snap ought to be assembled. However, most `snapcraft.yaml` files have the same common elements, including a number of mandatory declarations. Below is a short list of these keys, which will be further explained in the Examples sections later in the tutorial. |
There was a problem hiding this comment.
As we call out that only some keys are mandatory, should we specify in 46-50 which of them are mandatory? Parts and Apps are both optional, for instance - but one wouldn't know it from reading this.
| * A snap may contain one or more parts. | ||
| * A snap may contain one or more applications |
There was a problem hiding this comment.
"None or more", especially for apps -- snaps like mesa-core22 (and earlier/later iterations) don't include any apps, but merely serve content via a content interface.
| * The parts section may also include a list of [build packages](/t/build-and-staging-dependencies/11451) (build-packages) that will be used to create the snap applications but will not be included in the final snap. For instance, gcc or make. | ||
|
|
||
| The parts section may also include a list of [stage packages](/t/build-and-staging-dependencies/11451) (stage-packages) that will be used by the snap’s applications at runtime, e.g.: python-bcrypt. These will be obtained from the repository archives in the build instance. |
There was a problem hiding this comment.
Should we give a link to adding package repositories after these lines?
| The steps of a part goes through are as follows: | ||
|
|
||
| 1. **pull**: downloads or otherwise retrieves the components needed to build the part. You can use the [`source-*` keywords](/t/snapcraft-parts-metadata/8336#heading--source) of a part to specify which components to retrieve. If `source` points to a git repository, for example, the pull step will clone that repository. | ||
| 1. **build**: constructs the part from the previously pulled components. The [`plugin`](/t/snapcraft-plugins/4284) of a part specifies how it is constructed. The [`meson` plugin](/t/the-meson-plugin/8623), for example, executes `meson` and `ninja` to compile source code. Each part is built in a separate directory, but it can use the contents of the staging area if it specifies a dependency on other parts using the `after` keyword. See [Step dependencies](#heading--step-dependencies) for more information. |
There was a problem hiding this comment.
I will note that organize is missing -- considering its importance and relationship to the stage and prime keywords, it should be included here.
There was a problem hiding this comment.
We have a problem in the existing docs where they imply that organize it itself a step, rather than a before/after events. organize belongs to Stage, not Build, so I think we should be careful about where we lodge the keys and how we organise the lifecycle.
One way we could model and present the timeline is with – to use an idea from music – on beat events for steps (one and two and) and off beat events for the in-between procedures (one and two and). Shown as a tree:
- Pull
after- etc
- Overlay
overlay-script(to borrow a case from Rockcraft)- etc
- Build
build-packagesbuild-snaps- etc
For absolute correctness, it would probably need to be presented as a table that resembles a gantt-like schedule.
If we did this, whether we include all the keys remains a question. There are many. I think Sophie is already on the right track by including the most important in-between events and providing examples.
Do you think this could be a helpful way to map the steps?
There was a problem hiding this comment.
I'm not familiar with such a style, but it's potentially a helpful way of organizing this information -- at the very least, I wouldn't see any harm in attempting adding a structure like this!
Is it not the case that organize belongs to the build step? I believe organized bits will end up modified in the part's $CRAFT_PART_INSTALL, which then carries over into $CRAFT_STAGE.
There was a problem hiding this comment.
Is it not the case that
organizebelongs to the build step?
I might be misled. organize is described as both part of the stage step and the build step.
@mr-cal Which is correct?
There was a problem hiding this comment.
organize is the last event in the build step. It moves files within $CRAFT_PART_INSTALL.
I believe organized bits will end up modified in the part's $CRAFT_PART_INSTALL, which then carries over into $CRAFT_STAGE.
@dilyn-corner is correct here.
|
Thank you @dilyn-corner and @medubelko for your precious comments! I will take all that into account and create new commits very soon! |
First step into moving the Parts lifecycle into Snapcraft's reference: create the reference.
It is missing the additional work and redirect links on the other Snapcraft pages.