SliTaz Repositories

     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/linux/stuff/devtools/README	Fri Nov 15 16:49:43 2019 +0100
     1.3 @@ -0,0 +1,135 @@
     1.4 +SliTaz Linux Kernel Readme
     1.5 +==========================
     1.6 +
     1.7 +1. Updating the Kernel version
     1.8 +------------------------------
     1.9 +
    1.10 +There's a tiny tool called `up-linux.sh`: just update $VERSION in the main
    1.11 +"linux" receipt and then run this script. Versions in the all the related
    1.12 +packages will be updated. We can do it easy because we have defined variables
    1.13 +in the "linux" package receipt:
    1.14 +
    1.15 +  * SPLIT: list of packages that use files compiled with the "linux" package;
    1.16 +  * SIBLINGS: list of packages that builds using the same sources, but with
    1.17 +    the different purpose (to build man pages, API headers, config tool, etc).
    1.18 +
    1.19 +
    1.20 +2. Updating the Kernel config
    1.21 +-----------------------------
    1.22 +
    1.23 +You can use your old `.config` to build newer Kernels: it'll forgive you some
    1.24 +inconsistency in the configuration doing it's best. Note, using old `.config`
    1.25 +you'll lack the new possibilities provided by the new Kernel, while some older
    1.26 +options may no longer be used.
    1.27 +
    1.28 +To update the configuration options you may use your old `.config` as the base
    1.29 +(see `stuff/linux-slitaz.config`) with the tool provided in the "slitaz-dev"
    1.30 +package (please, read it's description).
    1.31 +
    1.32 +Some useful links provided by Thomas Hinterberger (a.k.a. Kult-ex) where you
    1.33 +can get examples of configs used in the different Linus distributions:
    1.34 +
    1.35 +  * Opensuse: https://github.com/openSUSE/kernel-source/blob/master/config/i386/default
    1.36 +  * Fedora:   http://pkgs.fedoraproject.org/cgit/rpms/kernel.git/refs/
    1.37 +  * Alpine:   https://github.com/alpinelinux/aports/blob/master/main/linux-vanilla/config-vanilla.x86
    1.38 +  * Manjaro:  https://github.com/manjaro/packages-core/blob/master/linux49/config
    1.39 +
    1.40 +It is strongly NOT recommended to just edit `.config` as text file (unless you
    1.41 +know all the consequences):
    1.42 +
    1.43 +    Automatically generated file; DO NOT EDIT.
    1.44 +
    1.45 +You may make mistakes. Geven module can't be builtin (=y) if it depends on the
    1.46 +loadable module (=m). Switching some options on (=y) and off (# ... is not set)
    1.47 +will add or remove a bunch of other options. Switching some option on may
    1.48 +automatically switch some other option on, as described in the Kconfig* files:
    1.49 +
    1.50 +  * selecting CONFIG_BLOCK will auto-select CONFIG_SBITMAP too
    1.51 +    (see $src/block/Kconfig);
    1.52 +  * CONFIG_SND_HDA_I915 depends on CONFIG_DRM_I915 and CONFIG_SND_HDA_CORE
    1.53 +    (see $src/sound/hda/Kconfig).
    1.54 +
    1.55 +It's (near to) impossible to track all that dependencies in mind.
    1.56 +
    1.57 +How do you know it's time to reconfigure your Kernel? Check cooking log for the
    1.58 +"(NEW)" items. The greater their number the stronger you need to reconfigure it.
    1.59 +
    1.60 +
    1.61 +3. Splitting the Kernel modules
    1.62 +-------------------------------
    1.63 +
    1.64 +Yet another big task is to split Kernel modules into different "linux-*"
    1.65 +packages. We need to keep the main "linux" package light, splitting rarely used
    1.66 +options into another packages.
    1.67 +
    1.68 +We need to keep balance between number of "linux-*" packages and the number of
    1.69 +the modules inside them. Package with the only one module, as well as package
    1.70 +with the thousands of modules are not a good solution. User will not need the
    1.71 +most of the modules in the package thanks to the great variety of sound cards,
    1.72 +network cards and other hardware that performs a similar function, but which
    1.73 +can not be present simultaneously in one configuration of the user equipment.
    1.74 +
    1.75 +Since Linux Kernel 4.9 we use special rules to find and split the modules into
    1.76 +the different "linux-*" packages, as well as to find modules that should be
    1.77 +inside the base "linux" package (please, see $stuff/split.rules). Rules format
    1.78 +is simple: one rule on line; each rule composed from two parts separating
    1.79 +spaces:
    1.80 +
    1.81 +  * ruleset name: we use "acpi" for "linux-acpi" package, "crypto" for
    1.82 +    "linux-crypto" package, etc. We use just "linux" for the base "linux"
    1.83 +    package. Note, we may use the same rules for the "linux64-*" and
    1.84 +    "linux-libre-*" packages as well as for "linux-*" packages.
    1.85 +  * rule itself: it's just the job for the `find` command making you free to
    1.86 +    add/remove modules more frequently than changing the rules itself. It save
    1.87 +    you from listing all the thousands of modules here. Three different examples
    1.88 +    of the rules itself showing their simplicity, strength and flexibility:
    1.89 +
    1.90 +    * `drivers/net/tun.ko.xz`: find and copy given module;
    1.91 +    * `net/bluetooth`: find and copy all the modules inside the given directory
    1.92 +      as well as from all including sub-directories;
    1.93 +    * `net/ipv4/*.ko.xz`: the same as above but only in the given directory,
    1.94 +      skipping all including sub-directories.
    1.95 +
    1.96 +Processing rules also automatically finds all the module dependencies to copy
    1.97 +all them too. So there's impossible situation with the missing dependencies.
    1.98 +
    1.99 +The goal is to copy each module to one or another package. Sometimes you need
   1.100 +to tweak existing rules or add new one. Please, make the rule as easier as you
   1.101 +can. If possible, avoid the particular module names, using directories names
   1.102 +instead. You'll see in the end of the cooking log if there's unpackaged modules.
   1.103 +
   1.104 +Also, there's little tool called `check-split.sh`. It produces a big bold table
   1.105 +containing all the modules with the information of packages where they lives now
   1.106 +and description provided with the certain module. You can run this script after
   1.107 +the splitting is over (after the "linux" package is done).
   1.108 +
   1.109 +You can open the table on the wide screen in the text editor, or convert it to
   1.110 +html using command `sundown modules.split > modules.split.html` and open it in
   1.111 +the web browser.
   1.112 +
   1.113 +Analizing the table will help you split the modules. If the certain module
   1.114 +belongs to two, three or more packages, it tells us that we need to put this
   1.115 +module to the base "linux" package: each "linux-*" package depends on the
   1.116 +"linux" package. But note, the single module may attract the bunch of other
   1.117 +modules as dependencies to the "linux" package, while this behavior may be
   1.118 +undesirable. Note, in some cases you may make the module builtin (=y).
   1.119 +
   1.120 +If the number of the packages belongs to two packages (for example to bigger
   1.121 +"linux-media" and to smaller "linux-radio") and we can easily differentiate
   1.122 +them, consider to use $DEPENDS on one of the receipt (the bigger one): package
   1.123 +"linux-media" is depends on "linux-radio" and all that common modules belongs
   1.124 +only to "linux-radio" package.
   1.125 +
   1.126 +Packages receipts are mostly generic, while all the splitting job is done by
   1.127 +script `$stuff/tools/copy_modules.sh` using the `$stuff/split.rules`.
   1.128 +
   1.129 +Steps to make split perfect:
   1.130 +
   1.131 +  1. Cook "linux" with all "linux-*" packages being cooking automatically too.
   1.132 +  2. Run `check-split.sh` and analize the modules table. Finish if you are
   1.133 +     satisfied with the result.
   1.134 +  3. Change `split.rules`.
   1.135 +  4. Run the command `cook linux --pack` to re-pack the "linux" and "linux-*"
   1.136 +     package using new rules.
   1.137 +  5. Examine the packing log: http://slitaz/cooker/cooker.cgi?log=linux-pack.log
   1.138 +  6. Proceed to step 2.