possibly rewriting the "shared state" section (and others?)

possibly rewriting the "shared state" section (and others?)

[Robert P. J. Day]

  pursuant to my tripping over a typo in the shared state section:

http://docs.yoctoproject.org/overview-manual/concepts.html#shared-state-cache

  it seems like that section (and many others) are unnecessarily
cumbersome far too early, in the sense of explaining the underlying
mechanics before simply telling the reader how to do something. case
in point: you need to read to almost the end of the whole section to
see a simple example of how to use SSTATE_MIRRORS.

  it seems like it should be the other way around -- "how can i save
all my sstate elsewhere on my disk to save piles of time?". here's an
example. *then* you back up and get into the intricacies. so let me
ask a couple (admittedly trivial) questions to make sure i grok this
and i'll ponder submitting some changes.

  in the sense of saving sstate-cache elsewhere on disk, it appears
that doing a simple "cp -a" or "mv" will do it, at which time i can
just set SSTATE_MIRRORS appropriately.

  first question: if i start from scratch and build a generic image
like "core-image-base", then save all sstate elsewhere, set
SSTATE_MIRRORS, delete tmp/ and build again, should i get *all* of my
build content from sstate? (unless there are recipes that explicitly
indicate they must be re-run no matter what?) i'm going to test this
right away building systemd-based core-image-base for aarch64 to see
what happens.

  second: as i extend my image, i will occasionally add a recipe that
has no saved sstate, so it will be built and sstate saved locally in
SSTATE_DIR in the build directory. if i want to add that to my global
sstate, is it just a matter of a simple "rsync" or something similar?

  last: i am simply assuming that it's probably a bad idea to set
SSTATE_DIR and SSTATE_MIRRORS to the same location trying to be
clever, because i'd want to have a mostly read-only SSTATE_MIRRORS to
be shared among developers, and not allow everyone to dump stuff in
there arbitrarily.

  thoughts?

rday

Re: [docs] possibly rewriting the "shared state" section (and others?)

[Alexander Kanavin]

[-- Attachment #1: Type: text/plain, Size: 2896 bytes --]

Just a general thought that I've often been frustrated by documentation
(especially manpages) that thinks it's a good idea to drown the reader in
rigorous definitions of the API, syntax and inner workings before getting
to actual examples (and most people learn by examples, fact).

Every document should start with a TL;DR section (not necessarily named so).

Alex

On Tue, 28 Sept 2021 at 11:14, Robert P. J. Day <rpjday@crashcourse.ca>
wrote:

>
>   pursuant to my tripping over a typo in the shared state section:
>
>
> http://docs.yoctoproject.org/overview-manual/concepts.html#shared-state-cache
>
>   it seems like that section (and many others) are unnecessarily
> cumbersome far too early, in the sense of explaining the underlying
> mechanics before simply telling the reader how to do something. case
> in point: you need to read to almost the end of the whole section to
> see a simple example of how to use SSTATE_MIRRORS.
>
>   it seems like it should be the other way around -- "how can i save
> all my sstate elsewhere on my disk to save piles of time?". here's an
> example. *then* you back up and get into the intricacies. so let me
> ask a couple (admittedly trivial) questions to make sure i grok this
> and i'll ponder submitting some changes.
>
>   in the sense of saving sstate-cache elsewhere on disk, it appears
> that doing a simple "cp -a" or "mv" will do it, at which time i can
> just set SSTATE_MIRRORS appropriately.
>
>   first question: if i start from scratch and build a generic image
> like "core-image-base", then save all sstate elsewhere, set
> SSTATE_MIRRORS, delete tmp/ and build again, should i get *all* of my
> build content from sstate? (unless there are recipes that explicitly
> indicate they must be re-run no matter what?) i'm going to test this
> right away building systemd-based core-image-base for aarch64 to see
> what happens.
>
>   second: as i extend my image, i will occasionally add a recipe that
> has no saved sstate, so it will be built and sstate saved locally in
> SSTATE_DIR in the build directory. if i want to add that to my global
> sstate, is it just a matter of a simple "rsync" or something similar?
>
>   last: i am simply assuming that it's probably a bad idea to set
> SSTATE_DIR and SSTATE_MIRRORS to the same location trying to be
> clever, because i'd want to have a mostly read-only SSTATE_MIRRORS to
> be shared among developers, and not allow everyone to dump stuff in
> there arbitrarily.
>
>   thoughts?
>
> rday
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#1896):
> https://lists.yoctoproject.org/g/docs/message/1896
> Mute This Topic: https://lists.yoctoproject.org/mt/85920423/1686489
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [
> alex.kanavin@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>
>

[-- Attachment #2: Type: text/html, Size: 4030 bytes --]