+BUILD
+=====
+
+As this is packaging for the Linux kernel with some extra integrations, like
+ZFS, this repo cannot be handled like a plain Linux kernel git repository.
+
+The actual Linux kernel source lives in a git submodule.
+
+For a build you should init the submodules and then handle it like most our
+Debian packaging builds. If unsure you can follow this:
+
+Installing Build-Dependencies
+-----------------------------
+
+You can either just check the package metadata template `debian/control.in`
+and install the packages listed in the `Build-Depends` section manually
+(replace `debhelper-compat` with just `debhelper`) or use a more automated way
+described below:
+
+ # install base build-dependencies and helpers
+ apt update
+ apt install devscripts
+
+ # create build-directory so that we got final packaging control files from the
+ # .in templates generated
+ make build-dir-fresh
+
+ # install build-dependencies (replace BUILD-DIR with actual one)
+ mk-build-deps -ir BUILD-DIR/debian/control
+
+
+Package Build
+-------------
+
+ # start the actual build
+ make deb
+
+For simple KConfig modifications you can adapt the list in `debian/rules` file.
+For quick code changes to the actual kernel code you can do them directly in
+the submodule/ubuntu-kernels directory, then re-create the build-directory, e.g.:
+
+ make clean
+ # now build again, explicitly creating the build-dir isn't required anymore
+ # after one has the build-dependencies already installed.
+ make deb
+
+
+Modify-Build-Test Cycles
+------------------------
+
+Ideally you avoid the need for doing a full package build and just directly
+build linux from the ubuntu-kernels or the mainline (stable) repo with copying
+over a build-config of a proxmox-kernel to that as .config and then using the
+`make olddefconfig` target.
+
+If you need full package builds you can try to make changes inside the
+BUILD-DIR directly and then continue build from there, e.g., using
+`dpkg-buildpackage -b -uc -us --no-pre-clean`. Depending on what stage you want
+to continue build you might need to touch, or remove some *.prepared files.
+Just check `debian/rules` for how kernel build progress is tracked by make.
+
+SUBMODULE
+=========
+
+We track the current upstream repository as submodule. Besides obvious
+advantages over tracking binary tar archives this also has some implications.
+
+For building the submodule directory gets copied into build/ and a few patches
+get applied with the `patch` tool. From a git point-of-view, the copied
+directory remains clean even with extra patches applied since it does not
+contain a .git directory, but a reference to the (still pristine) submodule:
+
+$ cat build/ubuntu-kernel/.git
+
+If you mistakenly cloned the upstream repo as "normal" clone (not via the
+submodule mechanics) this means that you have a real .git directory with its
+independent objects and tracking info when copying for building, thus git
+operates on the copied directory - and "sees" that it was dirtied by `patch`,
+and thus the kernel buildsystem sees this too and will add a '+' to the version
+as a result. This changes the output directories for modules and other build
+artefacts and let's then the build fail on packaging.
+
+So always ensure that you really checked it out as submodule, not as full
+"normal" clone. You can also explicitly set the LOCALVERSION variable to
+undefined with: `export LOCALVERSION= but that should only be done for test
+builds.
+
projects / pve-kernel.git / blobdiff