> I've been working on this for days now and I still don't know quite what
> I'm doing or why I have so much grief from the build system. I'd like to
> learn how, and then I'd like to write it down in the Wiki.
>
> What I'm doing should be pretty typical for a Balloon user and developer:
> working on adding support for different hardware in to the kernel. This is
> what Balloon is for, and a major part of its value. We need to make it
> easy, and tell people how to do it.
>
> Here's what I'm doing at the moment:
> - check out head of menuconfig2 branch from svn
> - make menuconfig
> - build everything
> - make kernel-menuconfig, choose the things which are important to me (in
> this case, various sound drivers, USB RNDIS old-kernel hack)
> - make
> - check that the basic setup works on the board.
>
> So far so good, all credit to the team who've put together the build system.
>
> Now I want to change things.
>
> I want to, in this case, add source for a couple of new kernel modules
> (/sound/soc/pxa/balloon3-tt.c and /sound/soc/codecs/ttdsp.c), the
> associated Kconfig adjustments, and probably modify
> /arch/arm/mach-pxa/balloon3.c and include/mach/balloon3.h for some
> low-level startup support.
>
> Nick B has done most of this, but I'd like to understand it better.
>
> We have a patch, balloon3-i2s.patch in this case, which can be managed by
> quilt. Fine.
>

I can describe what I do as it seems to work.
There may be many other ways of acheiving the same end of course.

One thing is definitely flakey in the buid system. All kernel builds are 
invalidated if you change the menuconfig board type without cleaning the 
kernel build. This is because of the *.stamp files not being cleaned out 
when the board changes. I guess I should look at automating that.

> How do I decide where to put this patch in the series? How do I find the
> right place in /package/kernel? Which series file should I modify?
>
If you type "quilt new foo.patch" it will create a new patchfile appended 
to the series in current use. So as not to have patch-on-patch confusion it 
is a *really* good plan to make the patch *not* use any files in any other 
patch, then it doesn't matter where it goes in the series. If it does use 
files in another patch, place it at the end of the series file but you have 
to be terribly careful about the quilt patch stack before doing a "quilt 
refresh" or you may inadvertently pollute anther patch which may affect 
other series. This was a common problem in trunk a while back.

> My workflow goes something like this:
> - build kernel (make at menuconfig2 top level)
> - download to board, test, discover bugs as expected
> - in build tree:
> - quilt pop balloon3-i2s
> - edit various files. Some of these are in the patch, others won't be. For
> example, I've put debug code in /arch/arm/mach-pxa/mfp-pxa2xx.c which I
> don't expect to become part of the patch but makes my development job easier.
> - quilt refresh
> - back at menuconfig2 top level, make again.
>
That sounds wrong as I don't use pop <name> though the docs say you should 
be ok. You need to have the balloon3-i2s.patch at the top of the quilt 
stack (not popped) when issuing the quilt refresh. quilt top will confirm.

> What happens now seems to be unpredictable. My kernel .config tends to get
> forgotten, which wastes a lot of time. I have to copy that into
> /package/kernel/.../balloon3config-whatever..., don't I?
>
> It's quite common that the kernel just won't build. For example, at this
> very moment, if I try to make, it dies with 'balloon3_gpio_vbus
> undeclared'. It seems not to have reapplied the patch series. Why not?
>
Not unless you re-unpack the kernel and get the kernel package Makefile 
apply the quilt series anew in my experience. There is however a steady 
trickle of complaints about this exact problem (vbus) so it needs 
identifying. If you want to make the current kernel .config the default for 
a particular board, you need to copy it into the balloon3config<board> file 
in the kernel patches dir if you are going to restart something which 
requires quilt.stamp (and series.stamp) to be updated eg after a make clean 
or a manual removing of the stamp. I tend not to do this so I don't find a 
problem.

> If I quilt push -a, then try make again, it starts asking me config
> questions. Why? Why? Note that I'm making in menuconfig2, not /build/kernel.
>
That should only happen if you have added configuration elements (eg in a 
Kconfig file) and not initialised .config (by make kernel-menuconfig) to 
use them. It finds new entries that are not initialised and reverts to 
asking you tedious questions.

> To get to this state, all I did was move some edits from one patch to
> another. I'd patched balloon3.c in balloon3-i2s.patch, which is bad news
> because that file is already patched in balloon3.patch. So I decide to fix
> that. No problem:
>
> - quilt pop balloon3-i2s
> - copy the changes out of the files into a blank buffer
> - quilt remove /arch/arm/mach-pxa/balloon3.c
> - quilt refresh
> - quilt pop balloon3
> - paste changes into /arch/arm/mach-pxa/balloon3.c
> - quilt refresh
>
> But now the kernel won't build, see above.
>
I do not use quilt pop <patchname>. I do quilt pop/push till the patch I 
want is on the top. Whether this is necessary I don't 100% know but it 
works for me.

When moving sub-patches I normally copy the patch data from the foo.patch 
file, then do a quilt pop -a. Remove the patch data from foo.patch, pup it 
in bar.patch and do quilt push -a. Work for me.

> I don't want to throw my source tree away and start again because it's got
> changes in which aren't part of a patch, and I don't want to spend time
> tracking them down and recording them. I shouldn't have to do this, surely?
>
Correct.

> What's the *right* way to do this? Tell me, and I'll write it down
> somewhere that everyone can see.
>
> This sort of documentation is essential. We have a complex build system and
> no documentation on how it works, so anything other than a straightforward
> distro build feels dangerous. I want to help change that.
>
Good plan. I understand how I do it so maybe documenting that is a start.
Part of this is documenting how to avoid quilt pitfalls.

I will robustify the board variant change handling.

> Chris