1DDISKIT(1) General Commands Manual DDISKIT(1)
2
6 ddiskit - Red Hat tool for Driver Update Disk creation
7
9 ddiskit [-h] [-vvv] [-qQ] [-p PROFILE] [-R RES_DIR] [-T TEMPLATE_DIR]
10 [-P PROFILE_DIR] [-d] [-o DUMP_CONFIG_NAME] [-C KEY=VALUE]...
11 ACTION [ACTION_OPTIONS]...
12
14 ddiskit (pronounced dee-dis-kit) aids and simplifies the creation of
15 (back-ported) out-of-tree kernel module RPMs and Driver Update Disks
16 containing them. These RPMs and DUDs are deemed suitable for using
17 with distributions based on Red Hat Enterprise Linux. This version of
18 ddiskit supports RHEL 7 and backward-compatible with RHEL 6.
19 ddiskit assumes some workflow which is described in the USAGE EXAMPLE
21 section. It is tailored to the process used for developing and releas‐
22 ing Driver Update Disks, and, while it can be used for creating driver
23 packages for RHEL-based distributions in general, it also worth consid‐
24 ering other tools for the similar purpose, like dkms(8) or akmods(1).
25
28 Please refer to the Configuration generation section for the descrip‐
29 tion of "configuration option name" and "default value".
30 General options
32 -h, --help
33 Print a list of options. ddiskit will exit after this action,
34 ignoring the remainder of the command line.
35 -v, --verbosity
37 Increase output verbosity by 1. Value of 1 means verbose output
38 (it toggles printing of most of executed commands and all warn‐
39 ings), and value of 2 is useful for debugging (it enables print‐
40 ing of all the executed commands output, actions, and messages).
41 Value of 3 further increases output verbosity of issued rpm(1)
42 commands.
43 Configuration option name: defaults.verbosity
45 Default value: 0
46 -p PROFILE, --profile PROFILE
48 Configuration profile to use. Please refer to the Configuration
49 generation section for the additional information about pro‐
50 files.
51 Configuration option name: defaults.profile
53 Default value: none; "default" is provided in package configura‐
54 tion
55 -R RES_DIR, --res-dir RES_DIR
57 Resources directory. Used as a base of evaluation for template
58 and profile directory paths.
59 Configuration option name: defaults.res_dir
61 Default value: none; "/usr/share/ddiskit/" is a hard-coded
62 default.
63 -T TEMPLATE_DIR, --template-dir TEMPLATE_DIR,
65 Templates directory, used as a base for searching for spec or
66 module configuration templates. Please refer to the File path
67 evaluation section for the information regarding template file
68 path resolution.
69 Configuration option name: defaults.template_dir
71 Default value: none; "{res_dir}/templates" is a hard-coded
72 default.
73 -P PROFILE_DIR, --profile-dir PROFILE_DIR
75 Profiles directory, used as a base for searching for profiles.
76 Please refer to the File path evaluation section for the infor‐
77 mation regarding profile file path resolution.
78 Configuration option name: defaults.profile_dir
80 Default value: none; "{res_dir}/profiles" is a hard-coded
81 default.
82 -d, --dump-config
84 Dump the derived configuration after performing the action.
85 Configuration option name: defaults.dump_config
87 Default value: False
88 -o DUMP_CONFIG_NAME, --dump-config-name DUMP_CONFIG_NAME
90 Path to the file targeted for the configuration dump.
91 Configuration option name: defaults.dump_config_name
93 Default value: none; "{config}.generated" is a hard-coded
94 default.
95 -q, --quilt-enable
97 Enable quilt support. Please refer to the QUILT INTEGRATION
98 section for the information regarding quilt integration. The
99 option sets defaults.quilt_support configuration option to True.
100 -Q, --quilt-disable
102 Disable quilt support. The option sets defaults.quilt_support
103 configuration option to False.
104 -C KEY=VALUE, --config-option KEY=VALUE
106 Override arbitrary configuration option that have the name KEY
107 with VALUE. The KEY should follow the "{[sec‐
108 tion_name.]key_name}" syntax, and defaults section is assumed in
109 case section_name part is omitted. The argument can be used
110 multiple times in order to override multiple options.
111 Options for prepare_sources action
113 -c CONFIG, --config CONFIG
114 Path to the module configuration file.
115 Configuration option name: defaults.config
117 Default value: "module.config"
118 -t CONFIG_TEMPLATE, --config-template CONFIG_TEMPLATE
120 Configuration file template. Please refer to the File path
121 evaluation section for the information regarding configuration
122 template file path resolution.
123 Configuration option name: defaults.config_template
125 Default value: none; "config" is a hard-coded default.
126 -g GIT_DIRECTORY, --git-dir GIT_DIRECTORY
128 Path to .git directory containing repository from where source
129 files should be checked out.
130 Configuration option name: defaults.git_dir
132 Default value: none
133 -r REVISION, --git-revision REVISION
135 Revision specification at which source files should be checked
136 out from the repository.
137 Configuration option name: defaults.git_revision
139 Default value: "HEAD"
140 -d DIRECTORIES, --git-src-directory DIRECTORIES
142 Whitespace-separated list of paths which should be checked out
143 from the repository.
144 Configuration option name: defaults.git_src_directory
146 Default value: none
147 Options for generate_spec action
149 -c CONFIG, --config CONFIG
150 Path to the module configuration file.
151 Configuration option name: defaults.config
153 Default value: "module.config"
154 -t SPEC_TEMPLATE, --spec-template SPEC_TEMPLATE
156 RPM spec file template. Please refer to the File path evalua‐
157 tion section for the information regarding RPM spec template
158 file path resolution.
159 Configuration option name: defaults.spec_template
161 Default value: none; "spec" is a hard-coded default.
162 Options for build_rpm action
164 -c CONFIG, --config CONFIG
165 Path to the module configuration file.
166 Configuration option name: defaults.config
168 Default value: "module.config"
169 -a, --tar-all
171 Tar all files, including hidden ones (files with names starting
172 with dot). Otherwise, only files with names starting with non-
173 dot character will be added to the source tarball. The option
174 sets the value of the relevant configuration parameter to True.
175 Note that this check is independent from the check controlled by
176 the defaults.tar_strict configuration parameter.
177 Configuration option name: defaults.tar_all
179 Default value: False
180 -e, --tar-strict
182 Tar only expected files. Only the files with names matching the
183 regular expression pattern provided in defaults.src_patterns
184 configuration option will be added to the source tarball. The
185 option sets the value of the relevant configuration parameter to
186 True. Note that this check is independent from the check con‐
187 trolled by the defaults.tar_all configuration parameter.
188 Configuration option name: defaults.tar_strict
190 Default value: False
191 -s, --srpm
193 Force building of source RPM instead of binary one. ddiskit has
194 several heuristics (whether host architecture is among architec‐
195 tures targeted by module, whether RPM build check passes) that
196 detect possibility of binary RPM build and falls back to build‐
197 ing source RPM only in case they indicated that binary RPM build
198 is impossible; however, one can force building of source RPM
199 instead of binary one with this switch. The option sets the
200 value of the relevant configuration parameter to True.
201 Configuration option name: defaults.srpm
203 Default value: False
204 -m, --mock
206 Enable mock(1) usage for building RPM. See the MOCK SUPPORT
207 section for additional information.
208 Configuration option name: defaults.mock
210 Default value: False
211 -r MOCK_CONFIG, --mock-config MOCK_CONFIG
213 Which mock configuration should be used for building RPM.
214 Configuration option name: defaults.mock_config
216 Default value: "default"
217 -l, --mock-offline
219 Whether to pass --offline option to mock.
220 Configuration option name: defaults.mock_offline
222 Default value: False
223 -g LEVEL, --check-git-src LEVEL
225 Set the level of source code repository authenticity check. See
226 the SOURCE CODE VERIFICATION section for the details.
227 Configuration option name: defaults.check_get_src
229 Default value: 0
230 -G, --generate-spec-on-build
232 Call the generate_spec action at the beginning of the build_rpm
233 action execution. This saves for calling generate_spec action
234 separately each time module configuration or patch list are
235 changed (assuming that spec file does not need manual changes
236 after generation).
237 Configuration option name: defaults.generate_spec_on_build
239 Default value: 0
240 Options for build_iso action
242 -c CONFIG, --config CONFIG
243 Path to the module configuration file.
244 Configuration option name: defaults.config
246 Default value: "module.config"
247 -i ISOFILE, --isofile ISOFILE
249 File name for the output ISO.
250 Configuration option name: defaults.isofile
252 Default value: none; see also build_iso action description sec‐
253 tion.
254 Options for dump_config action
256 -c CONFIG, --config CONFIG
257 Path to the module configuration file.
258 Configuration option name: defaults.config
260 Default value: "module.config"
261 -o DUMP_CONFIG_NAME, --dump-config-name DUMP_CONFIG_NAME
263 Name of the file where to store configuration dump. This is the
264 same option as the -o option in the General options section, and
265 present here only for convenience.
266 Configuration option name: defaults.dump_config_name
268 Default value: none; "{config}.generated" is a hard-coded
269 default.
270
272 Configuration is a sectioned key-value store, with values being strings
273 and interpreted based on the context (see CONFIGURATION VALUES REFER‐
274 ENCE section for the reference) as strings, integers, booleans (see
275 Boolean values section for the details on boolean value derivation), or
276 arrays.
277 Configuration generation
279 In order to construct its configuration, ddiskit gathers configuration
280 options from the multiple sources, then performs some fixed processing.
281 The sources of configuration options are the following:
282 · Hard-coded defaults, present in ddiskit source code. These are
284 mostly for default configuration search paths and for other values
285 which are expected to be defined one way or another. Currently, it
286 contains the following configuration options:
287 · defaults section
289 · res_dir = "/usr/share/ddiskit"
291 · template_dir = "{res_dir}/templates"
293 · profile_dir = "{res_dir}/profiles"
295 · config_template = "config"
297 · quilt_support = True
299 · spec_template = "spec"
301 · src_patterns = "^Kbuild$|^Kconfig$|^Makefile$|^.*.[ch]$"
303 · global section
305 · module_vendor = "ENTER_MODULE_VENDOR"
307 · module_author = "ENTER_MODULE_AUTHOR"
309 · module_author_email = "ENTER_MODULE_AUTHOR_EMAIL"
311 · The "package" configuration. It contains the rest of the configura‐
313 tion option defaults which should be defined for proper operation
314 (like spec file generation). Package configuration is read from the
315 fixed path "/usr/share/ddiskit/ddiskit.config" which is not expected
316 to be modified by user or system administrator (and is usually over‐
317 written by package update).
318 · The "site" configuration. Located in "/etc/ddiskit.config", this
320 file is treated as a configuration file and is subject to possible
321 changes by the system administrator.
322 · The "user" configuration. In case user wants some user-specific
324 changes (like his own default values for global.module_author or
325 global.module_author_email configuration options, as well as default
326 profile), he should place it in ".ddiskitrc" file in his home direc‐
327 tory.
328 · Profile. The profile in use is derived from defaults.profile and
330 default.profile_dir configuration variables (see more in the File
331 path evaluation section on how the path to the profile is evalu‐
332 ated). It contains overrides suitable for a particular use case
333 (for example, the rh-testing profile contains spec file description
334 suffix with a notice that the package provided is a testing pack‐
335 age). Note that the values for aforementioned configuration vari‐
336 ables can be overridden by -p and -P command line arguments.
337 · Module configuration. This file is usually called "module.config"
339 (but can be overridden by -c command line argument) and contains
340 module-specific configuration. It is usually generated from tem‐
341 plate by prepare_sources action and is self-documented in terms of
342 what values user is expected to provide there.
343 · Command-line arguments. They update defaults section of the configu‐
345 ration dictionary, and usually have key name equal to the long
346 option name, with dashes replaced with underscores. Configuration
347 option name for each specific command line option is provided in the
348 OPTIONS section. Unless explicitly specified (with default value
349 being "none"), command line option always updates the configuration
350 option value.
351 These files are applied one after another in aforementioned order, so
353 the "last wins" rule applies. The exception from the rule are command
354 line options, which take precedence at each point of configuration gen‐
355 eration (during the profile path evaluation, for example).
356 The configuration files themselves are sectioned key-value files with a
358 syntax described in related python module documentation ⟨https://
359 docs.python.org/2/library/configparser.html⟩, except for the interpola‐
360 tion part, which is home-grown and described in the section Configura‐
361 tion value evaluation.
362 Kernel package versioning scheme
364 Red Hat Enterprise Linux follows specific kernel package versioning
365 scheme, and ddiskit employs it in order to generate proper dependencies
366 on the kernel package. As a result, it expects that in places where
367 kernel version is provided, this version follows specific scheme. More
368 specifically, two version schemes are supported:
369 · Y-stream kernel version. This kernel package version is shipped as
371 a part of General Availability release, and has the following for‐
372 mat:
373 kernel_version.kernel_patchlevel.kernel_sublevel-rhel_release.rpm_dist
375 For example, RHEL 7.3 GA kernel has kernel version 3.10.0-514.el7.
377 As a result, it is expected that kernel_version, kernel_patchlevel,
378 kernel_sublevel, rhel_release are decimal numbers (having no more
379 than 1, 2, 2, and 4 digits, respectively), and rpm_dist part is pro‐
380 vided in the form of "el<number>", where <number> is a 1-digit or
381 2-digit number not less than 6.
382 · Z-stream kernel version. These kernel packages are provided as a
384 part of updates for the existing release (so-called Z-stream). The
385 versions of these packages have the following format:
386 kernel_version.kernel_patchlevel.kernel_sublevel-rhel_release[.update_release]+.rpm_dist
388 The restrictions on the parts that also used for the Y-stream kernel
390 package version description are the same, and update_release is a
391 number that can have up to 3 digits. Example of a Z-stream kernel
392 package version (RHEL 7.3 update from 2017-05-25):
393 3.10.0-514.21.1.el7.
394 Generally, it is expected that kernel module RPMs and Driver Update
396 Disks are built for using along with the Y-stream GA kernel (and all
397 the following Z-stream kernels, thanks to kABI compatibility), so when
398 Z-stream kernel package version is detected, the user is warned about
399 this. The differences between kernel package dependency generation in
400 these cases are described in the Spec file generation section.
401 In order to enforce these checks, ddiskit uses regular expression-based
403 approach: it checks the version provided in the defaults.kernel_version
404 configuration variable against regular expressions set via the
405 defaults.kernel_flex_version_re and defaults.kernel_fixed_version_re
406 configuration options, which contain Python regular expressions (see
407 Python re module documentation ⟨https://docs.python.org/2/library/
408 re.html⟩ for details about regular expression syntax) for matching Y-
409 stream and Z-stream kernel versioning scheme, respectively. In order
410 to extract parts of kernel version described above, the following regu‐
411 lar expression groups are used:
412 version Kernel's major version (kernel_version in the
414 description above).
415 patchlevel Kernel's patch level (kernel_patchlevel).
416 sublevel Kernel's sub-patch level (kernel_sublevel).
417 rpm_release Major part of RPM release (rhel_release).
418 rpm_release_add Remaining part of RPM release (update_release).
419 rpm_dist RPM release dist part (rpm_dist).
420 The default values of the defaults.kernel_flex_version_re and
422 defaults.kernel_fixed_version_re configuration options are set via
423 other configuration options:
424 kernel_flex_verson_re = {kernel_nvr_re}{kernel_dist_re}
426 kernel_fixed_version_re = {kernel_nvr_re}{kernel_fixed_re}{kernel_dist_re}
427 kernel_nvr_re = (?P<version>[0-9]).(?P<patchlevel>[0-9]{1,2}).(?P<sublevel>[0-9]{1,2})-(?P<rpm_release>[0-9]{1,4})
429 kernel_fixed_re = (?P<rpm_release_add>(.[0-9]{1,3})+)
430 kernel_dist_re = (?P<rpm_dist>.el([6-9]|[1-9][0-9]))
431 This allows for some flexibility in case some tuning of these checks is
433 needed.
434 Configuration check
436 After the configuration has been constructed (and in case module con‐
437 figuration is present), it is subject to a set of checks:
438 · Whether global and spec_file configuration sections are present.
440 · Whether all configuration options in global and spec_file sections
442 have non-default values. Default value is a value which is the con‐
443 catenation of "ENTER_" and upper-cased configuration key name
444 ("ENTER_MODULE_NAME" for spec_file.module_name configuration option,
445 for example). The exception is spec_file.firmware_version option, in
446 case spec_file.firmware_include configuration options is set to
447 False.
448 · Whether spec_file.kernel_version has proper format (only Y-stream
450 and Z-stream kernel versions are accepted).
451 File path evaluation
453 Paths to various external resource files (like templates and profiles)
454 are evaluated based on provided resource directory and name using the
455 following algorithm:
456 · If resource name does not have slashes, then it is considered that
458 this name refers to the file in the provided directory.
459 · Otherwise, it is interpreted as a path relative to the current work‐
461 ing directory (which is the directory the where module configuration
462 resides).
463 For example, profile "my-profile" is searched relative to profile
465 directory ("/usr/share/ddiskit/profiles" by default), but profile
466 "./my-profile" is searched relative to modules configuration directory.
467 Configuration value evaluation
469 Configuration option values can reference other configuration options
470 using the "{[section_name.]key_name}" syntax. If section is not
471 present, it is assumed that the referenced key is in the same section
472 as the value which references it. If the referenced key is not found,
473 no substitution occurs.
474 For example, let's assume the following configuration file:
476 [foo]
478 foo = aaa {bar} {bar.baz}
479 bar = bbb {baz} {bar.foo}
480 [bar]
482 foo = ccc {baz}
483 bar = ddd {foo.foo}
484 baz = eee
485 After the evaluation, foo.foo key would have the value "aaa bbb {baz}
487 ddd ccc eee eee", foo.bar would equal to "bbb {baz} ccc eee", bar.foo
488 would be "ccc eee", and bar.bar is "ddd ccc eee".
489 Circular dependencies are not explicitly resolved, there's only substi‐
491 tution depth limit present (which is set to 8 currently).
492 Boolean values
494 The values which are treated as boolean can have the following (case-
495 insensitive) values in order to indicate that the value should be eval‐
496 uated to True: 1, t, y, true, or yes. In order to indicate False
497 value, one of the following strings may be used: 0, f, n, false, or no.
498 In case configuration value doesn't evaluate to True or False value, it
499 is evaluated as None. None value is treated as False in most places,
500 but sometimes it is important to provide specific choice, and in these
501 cases error would occur if boolean value was evaluated to None.
502 Spec file generation
504 Before spec file generation takes place, additional configuration pro‐
505 cessing is performed:
506 · spec_file.source_patches and spec_file.source_patches_do generated
508 in accordance with a lexicographically sorted list of patch files
509 found in the patch directory (src/patch relative to current working
510 directory). spec_file.source_patches contains lines in the "PatchN:
511 patch-file-name" format, and spec_file.source_patches_do contains
512 lines in the "%patchN -p1" format. As a result, first configuration
513 variable is suitable for patch file list description, and second is
514 useful in the %prep section for patch applying. If the
515 default.quilt_support configuration option is enabled, file named
516 series is ignored in the patch directory.
517 · spec_file.firmware_files configuration variable contains list of
519 files found in the src/firmware directory with the /lib/firmware/
520 directory prepended, which is suitable for the %files section of the
521 firmware sub-package.
522 · spec_file.firmware_files_install configuration variable contains
524 list for firmware file installation commands in the format "install
525 -m 644 -D source/firmware/firmware-file-path
526 $RPM_BUILD_ROOT/lib/firmware/firmware-file-path", which is suitable
527 for the %install section of the firmware sub-package.
528 · spec_file.firmware_begin configuration option is set to "%if 1" or
530 "%if 0" when the spec_file.firmware_include configuration variable
531 is true or not, respectively.
532 · spec_file.firmware_end configuration variable is set to "%endif".
534 · spec_file.date is set to the current date and time in "%a %b %d %Y"
536 strftime(3) format, if this variable hasn't been set already.
537 · spec_file.kernel_requires is formatted as
539 Requires: kernel >= kernel_version-kernel_release.kernel_dist
541 Requires: kernel < kernel_version-(kernel_release + 1).kernel_dist
542 for the Y-stream kernel version, and
544 Requires: kernel = kernel_version-kernel_release.kernel_dist
546 for the Z-stream kernel version, if the variable hasn't been set
548 already (please refer to the Kernel package versioning scheme sec‐
549 tion for the additional details regarding Y-stream and Z-stream ver‐
550 sions).
551 · spec_file.module_requires is set to spec_file.dependencies value
553 with the "Requires: " string prepended, if the variable hasn't been
554 set already. Note that this special configuration variable is dep‐
555 recated, present only for the backward compatibility, and this spe‐
556 cial value generation may be removed in the future.
557 After this configuration processing, parts of the spec template in the
559 "%{[section_name.]key_name}" format (note the presence of percent sign
560 in comparison to the syntax used for configuration option substitution)
561 are replaced with evaluated configuration values. If no appropriate
562 configuration has been found, no replacement occurs. If configuration
563 option evaluates to empty string, "%{nil}" is inserted into the result‐
564 ing spec file.
565
567 prepare_sources
568 Prepare initial file and directory structure. This action creates
569 directories where various files are expected to be placed and creates
570 (into a file set in --config option) module configuration from the tem‐
571 plate file (which path is determined by the defaults.template_dir and
572 defaults.config_template configuration variables; please refer to the
573 File path evaluation section for the module configuration template path
574 derivation process). The action creates the following directory hier‐
575 archy:
576 · rpm - directory for storing rpmbuild(1) artifacts.
578 · BUILD - build directory, used by rpmbuild(1).
580 · BUILDROOT - RPM build root.
582 · RPMS - directory where resulting binary RPMs are stored.
584 · SOURCES - directory where source tarball and patches are stored.
586 · SPECS - directory where generated spec file is placed.
588 · SRPMS - directory where resulting source RPM is stored.
590 · src - directory where module sources are expected to be placed.
592 There are not explicit constrains on the kernel module source file
593 layout, but it is expected that the main make file is placed in a
594 directory provided in the spec_file.module_build_dir configuration
595 variable.
596 · patches - directory with patches that should be applied to the
598 source.
599 · firmware - firmware files.
601 Additionally, if the defaults.git_src_directory configuration option is
603 set, source files placed inside directories listed in this whitespace-
604 separated list checked out (inside the src directory) from the reposi‐
605 tory pointed by the defaults.git_dir configuration option at the revi‐
606 sion which specification is set in the defaults.git_revision configura‐
607 tion option (the actual revision to checkout is the output of git rev-
608 parse(1) command invocation with the aforementioned specification sup‐
609 plied to it).
610 Before configuration template is processed, the following configuration
612 options are also set:
613 · spec_file.module_build_dir - set to the value of first element of
615 whitespace-separated list stored in the defaults.git_src_directory
616 configuration option, or to "ENTER_MODULE_BUILD_DIR", if it is
617 empty.
618 · spec_file.git_hash - set to the value returned by get rev-parse(1)
620 call with defaults.git_revision revision specification supplied.
621 generate_spec
623 Generate spec file from the spec template (which path is determined by
624 the defaults.template_dir and defaults.spec_template configuration
625 variables; please refer to the File path evaluation section for spec
626 template path derivation process) using process described in Spec file
627 generation section. As a result of the execution of this action, the
628 "rpm/SPECS/{spec_file.module_name}.spec" file is generated. During the
629 generation process, the presence of kernel headers for the target ker‐
630 nel version and architectures is also checked, and warning message is
631 printed in case some of them are not present; this check doesn't affect
632 spec file generation process, however.
633 build_rpm
635 The RPM build action includes several steps:
636 · Check for the module configuration file presence (provided in
638 defaults.config configuration variable via the --config command line
639 option). Since some configuration values should be derived directly
640 from it, its absence makes the whole operation senseless, thus the
641 early bailout.
642 · Generate (if the defaults.generate_spec_on_build configuration
644 option is set to True) or check (if the defaults.check_spec_on_build
645 configuration option is set to positive value) spec file. Depending
646 on the check level provided in the defaults.check_spec_on build con‐
647 figuration option, the latter check may lead to warning or to the
648 termination of the action:
649 0 Do not perform the spec file check.
651 1 Perform spec file comparison and issue warning in case generated
653 and existing spec files differ.
654 2 Perform spec file comparison and issue warning in case generated
656 and existing spec files differ, user is asked whether he wants to
657 continue.
658 3 Perform spec file comparison and abort action execution in case
660 of any errors (during spec file generation or comparison).
661 No spec file comparison is performed (regardless of the
663 defaults.check_spec_on_build configuration option value) if spec
664 file generation is enabled (obviously).
665 · Check for the Makefile presence. Presence of file named "Makefile"
667 somewhere in the source tree allows for passing this check. Absence
668 of Makefile leads to early termination with a relevant exit code
669 (please refer to the EXIT STATUS section for details).
670 · In case quilt integration (specified via the configuration option
672 default.quilt_support) is enabled, quilt patches are de-applied.
673 · Source tarball creation. Tar file named "rpm/SOURCES/{spec_file.mod‐
675 ule_name}-{global.module_vendor}-{spec_file.module_version}.tar.bz2"
676 is created, and files present in the src directory added to it, with
677 the following exceptions:
678 · patches subdirectory is skipped.
680 · All RPM files present in the top level of the src directory are
682 skipped.
683 · Files present in the firmware source subdirectory are skipped in
685 case boolean configuration option spec_file.firmware_include is
686 set to False. In case there are files present in this directory,
687 warning message is displayed regarding the matter.
688 · Hidden files (files beginning with dot) are skipped, unless the
690 defaults.tar_all configuration option (controlled via the --tar-
691 all action-specific command line option) is set to True.
692 · Only files matching the pattern set in the defaults.src_patterns
694 configuration option are added, if the defaults.tar_strict con‐
695 figuration option (controlled via the --tar-strict action-spe‐
696 cific command line option) is set to True. The default pattern
697 includes only *.c, *.h, Makefile, Kbuild, and Kconfig files,
698 which should be suitable for the most cases.
699 · All files from the src/patches directory are copied to the
701 rpm/SOURCES directory.
702 · If current host architecture is among architectures provided in the
704 spec_file.kernel_arch architectures, rpmbuild check (rpmbuild -bc
705 --nobuild) succeeded, and the defaults.srpm configuration option
706 (controlled via the --srpm action-specific command line option) is
707 not enabled, an attempt to build binary RPM is performed. Other‐
708 wise, a source RPM is built.
709 · In case quilt integration (specified via the configuration option
711 default.quilt_support) is enabled, quilt patches are applied back.
712 build_iso
714 This action takes list of files and directories that should be placed
715 on the Driver Update Disk as a non-option arguments. It performs the
716 following steps:
717 · Iterate over the files provided in arguments (recursively descending
719 into directories) and add to the list of candidate files which sat‐
720 isfy the following criteria:
721 · file name ends with ".rpm",
723 · rpmquery(1) successfully retrieves information regarding RPM
725 architecture from the package,
726 · RPM is a binary package or RPM is a source package and the
728 global.include_srpm configuration option is enabled,
729 · RPM is not a debug information package (RPM has group other than
731 "Development/Debug"),
732 · RPM has a valid GPG signature (if case GPG signature check is
734 enabled; see RPM SIGNATURE VERIFICATION section for the addi‐
735 tional information).
736 · All satisfying candidates then copied in a temporary directory.
738 Source RPMs are placed in src subdirectory in the disk hierarchy,
739 and binary RPMs are placed in rpms/arch subdirectory, where arch is
740 the architecture of the binary RPM (with all variants of i386, ...,
741 i686 RPM architecture placed in the i386 subdirectory).
742 · RPM repository metadata is generated (using the createrepo(1) com‐
744 mand) in each of the aforementioned binary RPM directories.
745 · rhdd3 file containing Driver Update Disk signature is created in the
747 temporary directory.
748 · ISO image is created with the mkisofs(1) command. The name of the
750 ISO is provided in the defaults.isofile option (which can be set via
751 the --isofile action-specific command line option). In case no
752 explicit ISO file name is provided, it is generated as
753 "dd-{spec_file.module_name}-{spec_file.module_ver‐
754 sion}-{spec_file.module_rpm_release}.{spec_file.rpm_dist}.iso", or,
755 in case one of values of these configuration options is not a
756 string, simply "dd.iso".
757 dump_config
759 Dumps configuration dictionary as it has been evaluated by a process
760 described in the Configuration generation section. Output file for the
761 dump is set in the defaults.dump_config_name option.
762
764 ddiskit supports quilt(1) patch workflow. Specifically:
765 · It de-applies quilt patches before building source tarball and
767 applies them back after the build.
768 · It ignores series file in patches directory when builds a list of
770 patches during the generate_spec action, as well as during the tar‐
771 ball creation in the build_rpm action.
772 · It ignores hidden files during the tarball creation in the build_rpm
774 action which avoids inclusion of the .pc directory.
775 This behaviour (except the last part that is controlled by the
777 defaults.tar_all configuration option) is controlled by the
778 defaults.quilt_support configuration option, which is accessible via
779 the --quilt-enable and --quilt-disable command line options.
780
782 ddiskit supports using mock(1) for building RPM. This support is acti‐
783 vated via the defaults.mock configuration option which is controlled
784 via the --mock action-specific command line option. When mock support
785 is enabled, the following changes apply:
786 · mock(1) is called instead of rpmbuild for source and binary RPM cre‐
788 ation. Specifically, mock --buildsrpm is called for source RPM cre‐
789 ation and pair of mock --buildsrpm and mock --rebuild is used to
790 build binary RPM out of source RPM which is created inside mock
791 environment.
792 · No build check (rpmbuild -bc --nobuild) is performed in order to
794 check whether it is possible to build binary RPM, it is assumed that
795 mock can handle it.
796
798 As a part of the RPM build process (build_rpm action), source code can
799 be checked for the correspondence with the git repository from which
800 the code supposedly originates. It is assumed that the sources are
801 located in the subdirectory provided in the spec_file.module_build_dir
802 configuration option as of the commit whose ID is provided in the
803 spec_file.git_hash configuration option. The check is performed via
804 the git-diff(1) command. The path to the .git directory containing the
805 git repository against which module's source code should be checked has
806 to be provided in the defaults.git_repo configuration option. The
807 necessity of the check itself, as well as its crucialness is specified
808 via the default.check_git_src configuration option, with the following
809 meaning of its value:
810 0 The check is skipped.
812 1 The check is performed and the warning is issued if the sources dif‐
814 fer from the ones present in the repository.
815 2 The check is performed and the build process is aborted in case of
817 sources discrepancy or other issues during the check.
818 The source code verification is performed when quilt patches are
820 already de-applied.
821
823 As a part of ISO build process (build_iso action), included RPMs can be
824 checked for the presence and correctness of their GPG signature. The
825 necessity of check is controlled via the rpm_gpg_check.check_level con‐
826 figuration option, which can have one of the following values:
827 0 The check is skipped.
829 1 The check is performed and the warning is issued for each RPM that
831 failed it.
832 2 The check is performed and RPMs that didn't pass the check are
834 skipped.
835 3 The check is performed and ISO creation is aborted if one of RPMs
837 failed the check.
838 The boolean configuration option rpm_gpg_check.use_keyring controls
840 whether specific keyring directory containing specific set of keys
841 should be used or just GPG keys present in host's RPM DB. In case
842 usage of keyring directory is enabled, configuration option
843 rpm_gpg_check.keyring_dir points to the directory containing public GPG
844 keys. Note that in order to use these files, their names should end
845 with ".key" (this is, in fact, RPM's implicit assumption).
846 This check is enabled by default in rh-release profile and allows veri‐
848 fying that RPMs added to the release ISO have Red Hat's GPG signature.
849
851 1. Create initial directory structure and module configuration.
852 $ ddiskit prepare_sources
854 Writing new config file (module.config)... OK
855 Creating directory structure for RPM build ... OK
856 Creating directory structure for source code ... OK
857 Put your module source code in src directory.
858 2. Copy your code into the src directory:
861 $ tree src
863 src
864 ├── drivers
865 │ └── net
866 │ └── ethernet
867 │ └── broadcom
868 │ ├── Makefile
869 │ ├── tg3.c
870 │ └── tg3.h
871 └── patches
872 ├── 0001-test.patch
873 └── 0002-test.patch
874 · Please, respect the directory hierarchy for the drivers which are
877 originally part of the kernel tree.
878 · Additional patches for the code could be placed in the patches
880 directory.
881 3. Fill out the module.config and generate the spec file:
883 $ ddiskit generate_spec
885 Checking config ...
886 Config check ... OK
887 RPM spec file "rpm/SPECS/tg3.spec" exists!
888 Patches found, adding to the spec file:
889 Patch0: 0001-test.patch
890 Patch1: 0002-test.patch
891 Firmware directory is empty or nonexistent, skipping
892 Writing spec into rpm/SPECS/tg3.spec ... OK
893 · The resulting spec file is placed in the rpm/SPEC/ directory, you
896 can optionally check it out before proceeding.
897 4. Build binary RPM:
899 $ ddiskit build_rpm
901 5. Build Driver Update Disk ISO:
904 $ ddiskit build_iso
906
909 /usr/share/ddiskit.config
910 Package default configuration.
911 /etc/ddiskit.config
913 System-wide ("site") configuration.
914 ~/.ddiskitrc
916 User configuration.
917 module.config
919 Default configuration name.
920 /usr/share/ddiskit/templates/spec
922 Template for RPM spec file generation. Path to it can be over‐
923 ridden by changing defaults.spec_template configuration option
924 or defaults.template_dir, please refer to the File path evalua‐
925 tion section for the additional information.
926 /usr/share/ddiskit/templates/config
928 Template for module configuration. Path to it can be overridden
929 by changing defaults.config_template configuration option or
930 defaults.template_dir, please refer to the File path evaluation
931 section for the additional information.
932 /usr/share/ddiskit/profiles/default
934 Default profile. Contains configuration options which are use‐
935 ful in non-specific cases (none, currently). The profile in use
936 is selected via the defaults.profile configuration option. Path
937 to profile is configured by the defaults.profile_dir, configura‐
938 tion option, please refer to the File path evaluation section
939 for the additional information.
940 /usr/share/ddiskit/profiles/rh-testing
942 Profile which contains configuration options used for the test‐
943 ing DUP RPMs by Red Hat. This includes the disclaimer that the
944 package is provided for the testing purposes.
945 /usr/share/ddiskit/profiles/rh-release
947 Profile which contains configuration options used for the
948 release DUP RPMs by Red Hat. This includes enablement of vari‐
949 ous strict checks (such as Git commit ID and RPM GPG signature
950 verification).
951
953 0 successful execution.
954 1 generic error (no additional information available).
956 2 problems during command line argument parsing.
958 3 problems during the configuration check phase (see Configuration
960 check section for the additional information).
961 4 problem occurred when tried to de-apply quilt patches (patches
963 do not de-apply cleanly, for example).
964 5 problem occurred when tried to apply quilt patches.
966 6 problem occurred during the sources verification.
968 7 problem occurred during RPM GPG signature verification.
970 8 problem occurred during git checkout of source files.
972 9 problem occurred during spec file comparison.
974 32 generic input/output error.
976 34 error occurred while reading configuration file.
978 35 error occurred while writing module configuration file (pre‐
980 pare_sources action).
981 36 spec template file read error (generate_spec action).
983 38 spec read error (unused currently).
985 39 spec write error (generate_spec action).
987 41 source archive write error (build_rpm action).
989 42 Makefile not found (build_rpm action).
991 45 Driver Update Disk signature write error.
993 47 configuration dump file write error.
995 49 directory structure creation error.
997
999 Problems with ddiskit should be reported to ddiskit project bug tracker
1000 ⟨https://github.com/orosp/ddiskit/issues⟩
1001
1003 The initial version of ddiskit was created by John W. Linville in the
1004 year 2005 for 2.6-based Red Hat Enterprise Linux and Fedora Core dis‐
1005 tributions (like 2.6.9-based RHEL 4). It filled "the same need which
1006 Doug Ledford's Device Driver Update Disk Devel Kit filled for prior
1007 generations of Red Hat distributions" which was used for the Linux
1008 2.4-series based Red Hat distributions around the year 2003. In 2007,
1009 the responsibility for maintaining and enhancing ddiskit was passed to
1010 Jon Masters, who then developed ddiskit during the RHEL 5 and RHEL 6
1011 era. The third incarnation of ddiskit was conceived in 2016 by Petr
1012 Oroš in an attempt to bring more automation to the process of Driver
1013 Update Disk creation along with RHEL 7 support.
1014
1016 rpmbuild(1), dkms(8), akmods(1), mock(1), quilt(1)
1017 Jon Masters. Red Hat Driver Update Packages. Official Reference Guide
1019 ⟨http://people.redhat.com/jcm/el6/dup/docs/dup_book.pdf⟩
1020 ddiskit repository ⟨https://github.com/orosp/ddiskit/⟩
1022 DDISKIT(1)