Snapcraft.yaml reference

tobias · December 2, 2020, 3:47pm

This is missing the service ordering parts which are already documented for The snap format .

Name	Description
`apps.` `<app-name>.` `before` optional	List of applications that are ordered to be started before `<app-name>`. Applications must be part of the same snap. (snapd 2.31+) Type: `list[string]` Requires `daemon` to be set as the app type.
`apps.` `<app-name>.` `after` optional	List of applications that are ordered to be started after `<app-name>`. Applications must be part of the same snap. (snapd 2.31+) Type: `list[string]` Requires `daemon` to be set as the app type.

knkski · December 10, 2020, 7:57pm

It would be nice if this document talked about the /root/parts/<part-name>/* subdirectories where relevant.

For example, parts.<part-name>.organize says A map of files to rename / the key represents the path of a file inside the part and the value represents how the file is going to be staged.

But if I shell into the build container and go to /root/parts/<part-name>/, I see these subdirectories:

build
install
run
src
state

Does organize copy/rename those files from src to build? From src to install? From build to install?

Similarly, does parts.<part-name>.stage copy files from build to install? Or install to /root/stage? Does parts.<part-name>.prime only copy from /root/stage to /root/prime, or does it get involved in /root/parts/<part-name>/ somehow?

The context that I’d like to know all of this is that if I use say override-build and then run snapcraftctl build, I’m left unsure what steps have been run, and where the files have been put (build or install or /root/stage/?).

knkski · December 10, 2020, 8:03pm

It would also be great if sections like parts.<part-name>.override-build could talk about what exactly snapcraftctl build does. IIRC, it handles running parts.<part-name>.organize, so if you don’t run snapcraftctl build for whatever reason, the files don’t get organized.

fcole90 · December 12, 2020, 9:17am

Why do we need to edit the documentation in such a strange way instead of editing some md file on github? I don’t see any benefits in this approach, and many issues, like polluting this chat and needing to reference “where the section says X and Y it actually should be…”. I mean, this definitely doesn’t scale in the long term and seem to just become more and more confusing

lucyllewy · December 12, 2020, 8:43pm

I completely agree that this is not a suitable way to collaborate on docs, and. I’ve raised this as an issue both before and after the implementation. It seems that it’s the way that Canonical has decided to do things despite being unworkable/unscalable. Similarly the Ubuntu Discourse does the same thing for tutorials and docs specific to Ubuntu, also. Whenever I’ve raised this issue it has been stated that it’s fine and won’t be changing.

fcole90 · December 16, 2020, 9:26am

I created a thread for this, can you please write something to share your support?

ijohnson · February 4, 2021, 5:30pm

@degville can you add layouts to the reference here and maybe link to the other page we already have about layouts too?

degville · February 4, 2021, 5:34pm

Yes, of course - thanks for letting me know. I’ll update this post when it’s done.

Update: I’ve added Layout to the above reference and also to the top-level metadata document. I think we missed this because layouts had been experimental for so long.

kyleN · February 9, 2021, 2:13pm

missing refresh-mode: endure | restart?

degville · February 9, 2021, 4:36pm

Thanks for letting us know. I’ve added it above and also to the snapcraft app metadata document.

fcole90 · February 13, 2021, 4:18pm

Instead of proposing changes as a message, we can also edit the wiki directly, by clicking the green icon in the first post

sergiusens · March 24, 2021, 9:57pm

@degville can install-mode get documented here please?

degville · March 30, 2021, 11:57am

Thanks for flagging this missing option. I’ve now added it to the reference and other services-related docs.

stuart-warren · June 10, 2021, 8:41am

there is no mention of setting plugs for hooks that are documented on https://snapcraft.io/docs/supported-snap-hooks

This threw me for a long time and would have been helpful to have been here

degville · June 10, 2021, 9:24am

That’s a really good point - sorry it caused you to struggle, and it’s something that should be here. I’ll add hooks to this document.

lucyllewy · August 11, 2021, 12:19pm

I’ve updated the base keyword to indicate that it is now mandatory to specify a base snap unless the type is set to gadget, kernel, or base.

degville · August 11, 2021, 1:07pm

Thanks for the update, and for letting us know. That was a really useful addition.

rpjday · June 28, 2022, 9:13am

The information for “adopt-info” WRT snapcraft 7 seems incomplete. This page states that only “version” is a mandatory field that can be assigned via “adopt-info”. However, consider the source here:

github.com

snapcore/snapcraft/blob/main/snapcraft/projects.py#L227


class ContentPlug(ProjectModel):
    """Snapcraft project content plug definition."""
    content: Optional[str]
    interface: str
    target: str
    default_provider: Optional[str]
MANDATORY_ADOPTABLE_FIELDS = ("version", "summary", "description")
class Project(ProjectModel):
    """Snapcraft project definition.
    See https://snapcraft.io/docs/snapcraft-yaml-reference
    XXX: Not implemented in this version
    - system-usernames
    """

github.com

snapcore/snapcraft/blob/main/snapcraft/projects.py#L351-L358


@pydantic.validator("grade", "summary", "description")
@classmethod
def _validate_adoptable_field(cls, field_value, values, field):
    if not field_value and "adopt_info" not in values:
        raise ValueError(
            f"{field.name.capitalize()} must be declared if not adopting metadata"
        )
    return field_value

So it seems that “adopt-info” is associated with, at a minimum, grade, version, summary and/or description. Can this be clarified?

farshidtz · August 12, 2022, 3:18pm

Missing a hyperlink: https://www.freedesktop.org/software/systemd/man/systemd.service.html#RestartSec=

degville · August 23, 2022, 10:16am

Now added - thanks for the suggestion/fix!