util/kconfig/README.md

   1 # coreboot kconfig
   2
   3 This is coreboot's copy of kconfig which tracks Linux as upstream but comes
   4 with a few patches for portability but also a few semantic changes.
   5
   6 The patches that lead to this tree can be found in the patches/ subdirectory
   7 in a [quilt](http://savannah.nongnu.org/projects/quilt) friendly format that
   8 is also simple enough to manage manually with Unix tooling.
   9
  10 ## Updating kconfig
  11
  12 The first step is to unapply the patches. This can either be done with quilt
  13 in an already-configured tree (`quilt pop -a` should cleanly unapply them all)
  14 or manually if quilt doesn't have its tracking metadata around yet:
  15
  16 ```sh
  17 for i in $( ls patches/*.patch | tac ); do patch -p1 -R -i "$i"; done
  18 ```
  19
  20 The result should be a subtree that, apart from a few coreboot specific
  21 files on our side (e.g. documentation, integration in our build system)
  22 and a few files on the upstream end that we don't carry (e.g. the tests),
  23 is identical to the scripts/kconfig/ directory of Linux as of the most recent
  24 uprev we did. Check the uprev version by looking through
  25 `git log util/kconfig` output in our tree.
  26
  27 Assuming that you want to uprev from Linux 5.13 to 5.14, with a Linux git tree
  28 available in `~/linux`
  29
  30 ```sh
  31 cd util/kconfig && (cd ~/linux/ && git diff v5.13..v5.14 scripts/kconfig) | patch -p2`
  32 ```
  33
  34 applies the changes to your local tree.
  35
  36 Then reapply our patch train, which might be as simple as
  37 `quilt push -a --refresh` but might also require some meddling with the
  38 patches to make them apply again with the changes you just imported from
  39 Linux.
  40
  41 Check that kconfig still works, `git add` and `git commit` the changes and
  42 write a meaningful commit message that documents what Linux kconfig version
  43 the tree has been upreved to.
  44
  45 ## Adding a new patch
  46
  47 The format of the patches to kconfig is a mix of the headers produced by `git
  48 format-patch` and the patch format of quilt. However neither git nor quilt
  49 seems to have any functionality to directly produce a file in such a format
  50
  51 To add a patch in this format:
  52 1. Add your changes to the sources and `git commit` them
  53 2. Generate a git patch for the commit:
  54
  55     $ git format-patch HEAD~
  56
  57 3. Reverse apply the newly created patch file to restore the tree back to the
  58    state quilt thinks it is in:
  59
  60     $ git apply -R <the patch file>
  61
  62 4. Import the patch info quilt:
  63
  64     $ quilt import <the patch file>
  65
  66 5. Force push the change to the top of quilt's patch stack (quilt won't like
  67    the git diff style and would normally refuse to apply the patch):
  68
  69     $ quilt push -f <the patch file>
  70
  71 6. Add the changed files to be tracked against the quilt:
  72
  73     $ quilt add <the files you changed>
  74
  75 7. Re-apply your changes from the patch file:
  76
  77     $ git apply <the patch file>
  78
  79 8. Add the changes to quilt to regenerate the patch file in a quilt compatible
  80    format while keeping the git header:
  81
  82     $ quilt refresh
  83
  84 9. The new patch file and updated patches/series files can now be added to the
  85    git commit