README

   1 *** DO NOT RUN THIS without first reading the code and this README ***
   2
   3 This "script" is used to perform a complete Fedora rebuild
   4 of all OCaml packages, in build-requires order.
   5
   6 It requires the goals tool found here:
   7
   8   http://git.annexia.org/?p=goals.git;a=summary
   9
  10 You should usually use the version of goals compiled from that git
  11 repository (using the ./run script in the top directory) because we
  12 are still evolving goals and this script together.
  13
  14 In the video below I go into an explanation of how the goals tool
  15 works, and I definitely recommend watching it.  There is one
  16 relatively minor change we made to goals since this video was
  17 produced: tactics are now called "is-..." rather than using the
  18 asterisk (so for example "is-koji-built" instead of "*koji-built").
  19 Apart from that it generally still works as described in the video.
  20
  21   https://rwmj.wordpress.com/2020/01/14/goals-an-experimental-new-tool-which-generalizes-make/
  22
  23 Everything in this git repo is driven from the single "Goalfile".
  24 However it uses functions and tactics from the goals standard library,
  25 especially goals.git/stdlib/fedora.gl.  It's not really necessary to
  26 understand the library in detail, but keep this in mind in case you
  27 find a function or tactic in this Goalfile which doesn't appear to be
  28 defined anywhere.
  29
  30 You will need all Fedora OCaml packages checked out locally (or at
  31 least, all the ones which you want to rebuild).  To find a list of all
  32 OCaml packages, look in Koji here:
  33
  34   https://koji.fedoraproject.org/koji/search?match=glob&type=package&terms=ocaml*
  35
  36 and also look at the "other-packages" definition in Goalfile.
  37
  38 The Goalfile lets you set the path to where you have checked out these
  39 Fedora packages.  I use "~/d/fedora".
  40
  41 You will need to either be a Fedora Proven Packager, or have at least
  42 commit access to each OCaml package that you intend to rebuild, since
  43 building them involves pushing a Release bump.
  44
  45 Fedora builds are generally done into side tags, and this Goalfile can
  46 either build into a side tag or into a main Fedora branch (eg.
  47 "f99-build").  For major rebuilds it is Fedora policy to use a side
  48 tag.  You can choose by setting "fedora-tag" at the top of the
  49 Goalfile.
  50
  51 You will also need to decide on a unique string which identifies the
  52 build.  It should be a string which will never be reused (so don't use
  53 something generic like "OCaml rebuild.").  Also the string must not
  54 appear in the existing spec files already.  This is because we grep
  55 the spec file to decide if the package has already been rebuilt.
  56
  57 You can ignore packages by setting fedora-ignored.  We usually use
  58 this for packages which are broken and we are unable to fix
  59 immediately.
  60
  61 Packages must not have cyclic dependencies.  There are two packages in
  62 particular which need manual attention: ocaml-menhir and ocaml-dune.
  63 Both have "bootstrap" settings which you have to enable (see their
  64 specfiles).  Also you will have to remember to come back after the
  65 full rebuild, disable the bootstrap setting, and build those packages
  66 again.
  67
  68 So you're ready to do an OCaml rebuild?  Good, but first you must
  69 build the ocaml (compiler) package manually.  We don't automate this
  70 step (although we could) because we assume that the main reason we do
  71 an OCaml rebuild in the first place is because we want to update the
  72 compiler to a new version.
  73
  74 When you're ready to do a rebuild:
  75
  76 (1) Make sure your Kerberos key is refreshed.  If it expires during
  77     the process then all following builds will fail, which sucks.
  78
  79     kinit username@FEDORAPROJECT.ORG
  80
  81 (2) Similarly you may need to make sure your Fedora SSH key hasn't
  82     expired and ssh-agent is working.
  83
  84 (3) You probably want to set up screen/tmux if you are using a remote
  85     server because the whole rebuild will take quite a long time,
  86     possibly 1-2 days.
  87
  88 (4) On the first run (only), remove all .depcache files:
  89
  90     find ~/d/fedora -name .depcache -delete
  91
  92 (5) Assuming you have goals checked out and compiled in an adjacent
  93     directory, do:
  94
  95     ../goals/run goals -k
  96
  97 The -k option "keeps going" on failure (rebuilding all packages that
  98 don't depend on failed packages).  This is a personal preference: Do
  99 you want to get as much done as possible, or do you want to fix things
 100 as soon as possible?
 101
 102 You may also want to try the -j N option to limit (or increase) the
 103 number of parallel builds that will be run.  The default of goals is
 104 to use the same number of cores as your local machine, which is not
 105 very useful since you will be doing the actual builds on the Fedora
 106 koji servers.
 107
 108 As the script is running, builds will fly by because it's doing many
 109 parallel builds, but also there will be periods where it appears to
 110 have hung - these are caused by us waiting for Koji to build the
 111 newRepo.
 112
 113 The script will run for a long time, and (inevitably I'm afraid) fail.
 114 Pay careful attention to the failures, printed at the end, and also to
 115 Koji and email messages that you get.
 116
 117 The script as written at the moment will only attempt each build once.
 118 If a build fails you MUST fix it yourself (or add the package and
 119 dependencies to the ignored list).  An earlier version of the script
 120 did in fact keep retrying failed builds, but we found that wasn't very
 121 helpful.  When fixing and rebuilding a package, don't forget to
 122 rebuild it into the side tag (if using side tags) not into the main
 123 Fedora branches!
 124
 125 After the rebuild completes, don't forget to rebuild the bootstrap
 126 packages manually.  Then you will need to create a Bodhi update for
 127 the side tag.
 128
 129 Good luck!
 130
 131 Richard Jones, 19th April 2020