dev-manual: add command to force a recipe re-compile

Since this section talks about how to modify unpacked, temporary
source code, it only makes sense to tell readers how to re-build that
modified source.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

On Tue, 9 Jun 2026 at 21:20, Robert P. J. Day via
lists.yoctoproject.org <rpjday=crashcourse.ca@lists.yoctoproject.org>
wrote:
> --- a/documentation/dev-manual/temporary-source-code.rst
> +++ b/documentation/dev-manual/temporary-source-code.rst
> @@ -65,3 +65,11 @@ build system uses to build the package would be as follows::
>
>     project/build/tmp/work/qemux86-poky-linux/foo/1.3.0
>
> +Finally, if you make some changes to a recipe's unpacked source code,
> +you can force a re-compile of that recipe with the command::
> +
> +   $ bitbake -c compile -f recipe-name
> +
> +The ``-f`` option in the above forces that task to be re-run
> +(invalidating any existing stamp file).
> +

While explaining where to find the unpacked source is okay, taking it
further and providing a way to force-build it is not a good advice. If
someone needs to modify and build source like this, they should be
using 'devtool modify'.

Alex

On Wed, 10 Jun 2026, Alexander Kanavin wrote:

> On Tue, 9 Jun 2026 at 21:20, Robert P. J. Day via
> lists.yoctoproject.org <rpjday=crashcourse.ca@lists.yoctoproject.org>
> wrote:
> > --- a/documentation/dev-manual/temporary-source-code.rst
> > +++ b/documentation/dev-manual/temporary-source-code.rst
> > @@ -65,3 +65,11 @@ build system uses to build the package would be as follows::
> >
> >     project/build/tmp/work/qemux86-poky-linux/foo/1.3.0
> >
> > +Finally, if you make some changes to a recipe's unpacked source code,
> > +you can force a re-compile of that recipe with the command::
> > +
> > +   $ bitbake -c compile -f recipe-name
> > +
> > +The ``-f`` option in the above forces that task to be re-run
> > +(invalidating any existing stamp file).
> > +
>
> While explaining where to find the unpacked source is okay, taking it
> further and providing a way to force-build it is not a good advice. If
> someone needs to modify and build source like this, they should be
> using 'devtool modify'.

  i actually thought about adding a link to devtool, along the lines
of "while this technique works, devtool modify is now the recommended
way" or something like that, at least as a historical reference for
people who have been doing it the bitbake way all this time to let
them know there's a better way.

rday

On 6/10/26 10:36 AM, Robert P. J. Day via lists.yoctoproject.org wrote:
> On Wed, 10 Jun 2026, Alexander Kanavin wrote:
> 
>> On Tue, 9 Jun 2026 at 21:20, Robert P. J. Day via
>> lists.yoctoproject.org <rpjday=crashcourse.ca@lists.yoctoproject.org>
>> wrote:
>>> --- a/documentation/dev-manual/temporary-source-code.rst
>>> +++ b/documentation/dev-manual/temporary-source-code.rst
>>> @@ -65,3 +65,11 @@ build system uses to build the package would be as follows::
>>>
>>>      project/build/tmp/work/qemux86-poky-linux/foo/1.3.0
>>>
>>> +Finally, if you make some changes to a recipe's unpacked source code,
>>> +you can force a re-compile of that recipe with the command::
>>> +
>>> +   $ bitbake -c compile -f recipe-name
>>> +
>>> +The ``-f`` option in the above forces that task to be re-run
>>> +(invalidating any existing stamp file).
>>> +
>>
>> While explaining where to find the unpacked source is okay, taking it
>> further and providing a way to force-build it is not a good advice. If
>> someone needs to modify and build source like this, they should be
>> using 'devtool modify'.
> 
>    i actually thought about adding a link to devtool, along the lines
> of "while this technique works, devtool modify is now the recommended
> way" or something like that, at least as a historical reference for
> people who have been doing it the bitbake way all this time to let
> them know there's a better way.
> 

Do not modify a recipe's unpacked source code, it's the best way to have 
your changes lost. There are non-negligible chances that it'll end up 
being deleted and unpacked again (e.g. because the cache is outdated via 
its dependencies or the recipe parsing resulted in a rebuild of the recipe).

Using -f also taints the build and you need to clean the sstate-cache 
for this recipe to recover from it last time I checked, which is 
something we don't like recommending to people (if you need to clean the 
sstate-cache, either something's wrong with your recipe or there's a bug 
we need to fix), so I don't think documenting this enormous footgun is a 
good thing.

Cheers,
Quentin

On Wed, 10 Jun 2026 at 11:24, Quentin Schulz <quentin.schulz@cherry.de> wrote:
> Do not modify a recipe's unpacked source code, it's the best way to have
> your changes lost. There are non-negligible chances that it'll end up
> being deleted and unpacked again (e.g. because the cache is outdated via
> its dependencies or the recipe parsing resulted in a rebuild of the recipe).
>
> Using -f also taints the build and you need to clean the sstate-cache
> for this recipe to recover from it last time I checked, which is
> something we don't like recommending to people (if you need to clean the
> sstate-cache, either something's wrong with your recipe or there's a bug
> we need to fix), so I don't think documenting this enormous footgun is a
> good thing.

I agree, I'd rather not mention it at all, and point people directly to devtool.

Alex

On Wed, 10 Jun 2026, Quentin Schulz via lists.yoctoproject.org wrote:

>
>
> On 6/10/26 10:36 AM, Robert P. J. Day via lists.yoctoproject.org wrote:
> > On Wed, 10 Jun 2026, Alexander Kanavin wrote:
> >
> > > On Tue, 9 Jun 2026 at 21:20, Robert P. J. Day via
> > > lists.yoctoproject.org <rpjday=crashcourse.ca@lists.yoctoproject.org>
> > > wrote:
> > > > --- a/documentation/dev-manual/temporary-source-code.rst
> > > > +++ b/documentation/dev-manual/temporary-source-code.rst
> > > > @@ -65,3 +65,11 @@ build system uses to build the package would be as
> > > > follows::
> > > >
> > > >      project/build/tmp/work/qemux86-poky-linux/foo/1.3.0
> > > >
> > > > +Finally, if you make some changes to a recipe's unpacked source code,
> > > > +you can force a re-compile of that recipe with the command::
> > > > +
> > > > +   $ bitbake -c compile -f recipe-name
> > > > +
> > > > +The ``-f`` option in the above forces that task to be re-run
> > > > +(invalidating any existing stamp file).
> > > > +
> > >
> > > While explaining where to find the unpacked source is okay, taking it
> > > further and providing a way to force-build it is not a good advice. If
> > > someone needs to modify and build source like this, they should be
> > > using 'devtool modify'.
> >
> >    i actually thought about adding a link to devtool, along the lines
> > of "while this technique works, devtool modify is now the recommended
> > way" or something like that, at least as a historical reference for
> > people who have been doing it the bitbake way all this time to let
> > them know there's a better way.
> >
>
> Do not modify a recipe's unpacked source code, it's the best way to have your
> changes lost. There are non-negligible chances that it'll end up being deleted
> and unpacked again (e.g. because the cache is outdated via its dependencies or
> the recipe parsing resulted in a rebuild of the recipe).
>
> Using -f also taints the build and you need to clean the sstate-cache for this
> recipe to recover from it last time I checked, which is something we don't
> like recommending to people (if you need to clean the sstate-cache, either
> something's wrong with your recipe or there's a bug we need to fix), so I
> don't think documenting this enormous footgun is a good thing.

  i will point out that that very command is (sort of) recommended in
the section on quilt (see point 6.):

  https://docs.yoctoproject.org/dev-manual/quilt.html

i will ponder further but i think it's important to mention the
"bitbake" variation if only to say, "this is the way it was done
*historically*, but that way is fraught with peril and you are
vigorously encouraged to use the 'devtool' utility." because there are
certainly developers who still use the bitbake technique who should be
warned off of it.

  or is this not worth the trouble?

rday

On Wed, 10 Jun 2026, Alexander Kanavin wrote:

> On Wed, 10 Jun 2026 at 11:24, Quentin Schulz <quentin.schulz@cherry.de> wrote:
> > Do not modify a recipe's unpacked source code, it's the best way to have
> > your changes lost. There are non-negligible chances that it'll end up
> > being deleted and unpacked again (e.g. because the cache is outdated via
> > its dependencies or the recipe parsing resulted in a rebuild of the recipe).
> >
> > Using -f also taints the build and you need to clean the sstate-cache
> > for this recipe to recover from it last time I checked, which is
> > something we don't like recommending to people (if you need to clean the
> > sstate-cache, either something's wrong with your recipe or there's a bug
> > we need to fix), so I don't think documenting this enormous footgun is a
> > good thing.
>
> I agree, I'd rather not mention it at all, and point people directly to devtool.

  ok, i'll add that but, as i just mentioned, it's there in the quilt
section as well.

rday

On Wed Jun 10, 2026 at 11:51 AM CEST, Robert P. J. Day wrote:
> On Wed, 10 Jun 2026, Alexander Kanavin wrote:
>
>> On Wed, 10 Jun 2026 at 11:24, Quentin Schulz <quentin.schulz@cherry.de> wrote:
>> > Do not modify a recipe's unpacked source code, it's the best way to have
>> > your changes lost. There are non-negligible chances that it'll end up
>> > being deleted and unpacked again (e.g. because the cache is outdated via
>> > its dependencies or the recipe parsing resulted in a rebuild of the recipe).
>> >
>> > Using -f also taints the build and you need to clean the sstate-cache
>> > for this recipe to recover from it last time I checked, which is
>> > something we don't like recommending to people (if you need to clean the
>> > sstate-cache, either something's wrong with your recipe or there's a bug
>> > we need to fix), so I don't think documenting this enormous footgun is a
>> > good thing.
>>
>> I agree, I'd rather not mention it at all, and point people directly to devtool.
>
>   ok, i'll add that but, as i just mentioned, it's there in the quilt
> section as well.

I think keeping the Quilt document is fine and in this case the command makes
sense, however, it would be nice to inform users in this document that devtool
is available and friendlier. Could you add this note?

Antonin

On Wed, 10 Jun 2026, Antonin Godard via lists.yoctoproject.org wrote:

> On Wed Jun 10, 2026 at 11:51 AM CEST, Robert P. J. Day wrote:
> > On Wed, 10 Jun 2026, Alexander Kanavin wrote:
> >
> >> On Wed, 10 Jun 2026 at 11:24, Quentin Schulz <quentin.schulz@cherry.de> wrote:
> >> > Do not modify a recipe's unpacked source code, it's the best way to have
> >> > your changes lost. There are non-negligible chances that it'll end up
> >> > being deleted and unpacked again (e.g. because the cache is outdated via
> >> > its dependencies or the recipe parsing resulted in a rebuild of the recipe).
> >> >
> >> > Using -f also taints the build and you need to clean the sstate-cache
> >> > for this recipe to recover from it last time I checked, which is
> >> > something we don't like recommending to people (if you need to clean the
> >> > sstate-cache, either something's wrong with your recipe or there's a bug
> >> > we need to fix), so I don't think documenting this enormous footgun is a
> >> > good thing.
> >>
> >> I agree, I'd rather not mention it at all, and point people directly to devtool.
> >
> >   ok, i'll add that but, as i just mentioned, it's there in the quilt
> > section as well.
>
> I think keeping the Quilt document is fine and in this case the
> command makes sense, however, it would be nice to inform users in
> this document that devtool is available and friendlier. Could you
> add this note?

  there is alreaady a note at the top of the quilt section
recommending devtool.

rday

On Wed Jun 10, 2026 at 2:59 PM CEST, Robert P. J. Day wrote:
> On Wed, 10 Jun 2026, Antonin Godard via lists.yoctoproject.org wrote:
>
>> On Wed Jun 10, 2026 at 11:51 AM CEST, Robert P. J. Day wrote:
>> > On Wed, 10 Jun 2026, Alexander Kanavin wrote:
>> >
>> >> On Wed, 10 Jun 2026 at 11:24, Quentin Schulz <quentin.schulz@cherry.de> wrote:
>> >> > Do not modify a recipe's unpacked source code, it's the best way to have
>> >> > your changes lost. There are non-negligible chances that it'll end up
>> >> > being deleted and unpacked again (e.g. because the cache is outdated via
>> >> > its dependencies or the recipe parsing resulted in a rebuild of the recipe).
>> >> >
>> >> > Using -f also taints the build and you need to clean the sstate-cache
>> >> > for this recipe to recover from it last time I checked, which is
>> >> > something we don't like recommending to people (if you need to clean the
>> >> > sstate-cache, either something's wrong with your recipe or there's a bug
>> >> > we need to fix), so I don't think documenting this enormous footgun is a
>> >> > good thing.
>> >>
>> >> I agree, I'd rather not mention it at all, and point people directly to devtool.
>> >
>> >   ok, i'll add that but, as i just mentioned, it's there in the quilt
>> > section as well.
>>
>> I think keeping the Quilt document is fine and in this case the
>> command makes sense, however, it would be nice to inform users in
>> this document that devtool is available and friendlier. Could you
>> add this note?
>
>   there is alreaady a note at the top of the quilt section
> recommending devtool.

Ah perfect then.

Antonin