docs/manual/adding-packages-directory.adoc

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Package directory
   5
   6 First of all, create a directory under the +package+ directory for
   7 your software, for example +libfoo+.
   8
   9 Some packages have been grouped by topic in a sub-directory:
  10 +x11r7+, +qt5+ and +gstreamer+. If your package fits in
  11 one of these categories, then create your package directory in these.
  12 New subdirectories are discouraged, however.
  13
  14 === Config files
  15
  16 For the package to be displayed in the configuration tool, you need to
  17 create a Config file in your package directory. There are two types:
  18 +Config.in+ and +Config.in.host+.
  19
  20 ==== +Config.in+ file
  21
  22 For packages used on the target, create a file named +Config.in+. This
  23 file will contain the option descriptions related to our +libfoo+ software
  24 that will be used and displayed in the configuration tool. It should basically
  25 contain:
  26
  27 ---------------------------
  28 config BR2_PACKAGE_LIBFOO
  29         bool "libfoo"
  30         help
  31           This is a comment that explains what libfoo is. The help text
  32           should be wrapped.
  33
  34           http://foosoftware.org/libfoo/
  35 ---------------------------
  36
  37 The +bool+ line, +help+ line and other metadata information about the
  38 configuration option must be indented with one tab. The help text
  39 itself should be indented with one tab and two spaces, lines should
  40 be wrapped to fit 72 columns, where tab counts for 8, so 62 characters
  41 in the text itself. The help text must mention the upstream URL of the
  42 project after an empty line.
  43
  44 As a convention specific to Buildroot, the ordering of the attributes
  45 is as follows:
  46
  47 1. The type of option: +bool+, +string+... with the prompt
  48 2. If needed, the +default+ value(s)
  49 3. Any dependencies on the target in +depends on+ form
  50 4. Any dependencies on the toolchain in +depends on+ form
  51 5. Any dependencies on other packages in +depends on+ form
  52 6. Any dependency of the +select+ form
  53 7. The help keyword and help text.
  54
  55 You can add other sub-options into a +if BR2_PACKAGE_LIBFOO...endif+
  56 statement to configure particular things in your software. You can look at
  57 examples in other packages. The syntax of the +Config.in+ file is the same
  58 as the one for the kernel Kconfig file. The documentation for this syntax is
  59 available at http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]
  60
  61 Finally you have to add your new +libfoo/Config.in+ to
  62 +package/Config.in+ (or in a category subdirectory if you decided to
  63 put your package in one of the existing categories). The files
  64 included there are 'sorted alphabetically' per category and are 'NOT'
  65 supposed to contain anything but the 'bare' name of the package.
  66
  67 --------------------------
  68 source "package/libfoo/Config.in"
  69 --------------------------
  70
  71
  72 ==== +Config.in.host+ file
  73
  74 Some packages also need to be built for the host system. There are two
  75 options here:
  76
  77 * The host package is only required to satisfy build-time
  78   dependencies of one or more target packages. In this case, add
  79   +host-foo+ to the target package's +BAR_DEPENDENCIES+ variable. No
  80   +Config.in.host+ file should be created.
  81
  82 * The host package should be explicitly selectable by the user from
  83   the configuration menu. In this case, create a +Config.in.host+ file
  84   for that host package:
  85 +
  86 ---------------------------
  87 config BR2_PACKAGE_HOST_FOO
  88         bool "host foo"
  89         help
  90           This is a comment that explains what foo for the host is.
  91
  92           http://foosoftware.org/foo/
  93 ---------------------------
  94 +
  95 The same coding style and options as for the +Config.in+ file are valid.
  96 +
  97 Finally you have to add your new +libfoo/Config.in.host+ to
  98 +package/Config.in.host+. The files included there are 'sorted alphabetically'
  99 and are 'NOT' supposed to contain anything but the 'bare' name of the package.
 100 +
 101 --------------------------
 102 source "package/foo/Config.in.host"
 103 --------------------------
 104 +
 105 The host package will then be available from the +Host utilities+ menu.
 106
 107 [[depends-on-vs-select]]
 108 ==== Choosing +depends on+ or +select+
 109
 110 The +Config.in+ file of your package must also ensure that
 111 dependencies are enabled. Typically, Buildroot uses the following
 112 rules:
 113
 114 * Use a +select+ type of dependency for dependencies on
 115   libraries. These dependencies are generally not obvious and it
 116   therefore make sense to have the kconfig system ensure that the
 117   dependencies are selected. For example, the _libgtk2_ package uses
 118   +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
 119   enabled.
 120   The +select+ keyword expresses the dependency with a backward
 121   semantic.
 122
 123 * Use a +depends on+ type of dependency when the user really needs to
 124   be aware of the dependency. Typically, Buildroot uses this type of
 125   dependency for dependencies on target architecture, MMU support and
 126   toolchain options (see xref:dependencies-target-toolchain-options[]),
 127   or for dependencies on "big" things, such as the X.org system.
 128   The +depends on+ keyword expresses the dependency with a forward
 129   semantic.
 130
 131 .Note
 132 The current problem with the _kconfig_ language is that these two
 133 dependency semantics are not internally linked. Therefore, it may be
 134 possible to select a package, whom one of its dependencies/requirement
 135 is not met.
 136
 137 An example illustrates both the usage of +select+ and +depends on+.
 138
 139 --------------------------
 140 config BR2_PACKAGE_RRDTOOL
 141         bool "rrdtool"
 142         depends on BR2_USE_WCHAR
 143         select BR2_PACKAGE_FREETYPE
 144         select BR2_PACKAGE_LIBART
 145         select BR2_PACKAGE_LIBPNG
 146         select BR2_PACKAGE_ZLIB
 147         help
 148           RRDtool is the OpenSource industry standard, high performance
 149           data logging and graphing system for time series data.
 150
 151           http://oss.oetiker.ch/rrdtool/
 152
 153 comment "rrdtool needs a toolchain w/ wchar"
 154         depends on !BR2_USE_WCHAR
 155 --------------------------
 156
 157
 158 Note that these two dependency types are only transitive with the
 159 dependencies of the same kind.
 160
 161 This means, in the following example:
 162
 163 --------------------------
 164 config BR2_PACKAGE_A
 165         bool "Package A"
 166
 167 config BR2_PACKAGE_B
 168         bool "Package B"
 169         depends on BR2_PACKAGE_A
 170
 171 config BR2_PACKAGE_C
 172         bool "Package C"
 173         depends on BR2_PACKAGE_B
 174
 175 config BR2_PACKAGE_D
 176         bool "Package D"
 177         select BR2_PACKAGE_B
 178
 179 config BR2_PACKAGE_E
 180         bool "Package E"
 181         select BR2_PACKAGE_D
 182 --------------------------
 183
 184 * Selecting +Package C+ will be visible if +Package B+ has been
 185   selected, which in turn is only visible if +Package A+ has been
 186   selected.
 187
 188 * Selecting +Package E+ will select +Package D+, which will select
 189   +Package B+, it will not check for the dependencies of +Package B+,
 190   so it will not select +Package A+.
 191
 192 * Since +Package B+ is selected but +Package A+ is not, this violates
 193   the dependency of +Package B+ on +Package A+. Therefore, in such a
 194   situation, the transitive dependency has to be added explicitly:
 195
 196 --------------------------
 197 config BR2_PACKAGE_D
 198         bool "Package D"
 199         depends on BR2_PACKAGE_A
 200         select BR2_PACKAGE_B
 201
 202 config BR2_PACKAGE_E
 203         bool "Package E"
 204         depends on BR2_PACKAGE_A
 205         select BR2_PACKAGE_D
 206 --------------------------
 207
 208 Overall, for package library dependencies, +select+ should be
 209 preferred.
 210
 211 Note that such dependencies will ensure that the dependency option
 212 is also enabled, but not necessarily built before your package. To do
 213 so, the dependency also needs to be expressed in the +.mk+ file of the
 214 package.
 215
 216 Further formatting details: see xref:writing-rules-config-in[the
 217 coding style].
 218
 219 [[dependencies-target-toolchain-options]]
 220 ==== Dependencies on target and toolchain options
 221
 222 Many packages depend on certain options of the toolchain: the choice of
 223 C library, C++ support, thread support, RPC support, wchar support,
 224 or dynamic library support. Some packages can only be built on certain
 225 target architectures, or if an MMU is available in the processor.
 226
 227 These dependencies have to be expressed with the appropriate 'depends
 228 on' statements in the Config.in file. Additionally, for dependencies on
 229 toolchain options, a +comment+ should be displayed when the option is
 230 not enabled, so that the user knows why the package is not available.
 231 Dependencies on target architecture or MMU support should not be
 232 made visible in a comment: since it is unlikely that the user can
 233 freely choose another target, it makes little sense to show these
 234 dependencies explicitly.
 235
 236 The +comment+ should only be visible if the +config+ option itself would
 237 be visible when the toolchain option dependencies are met. This means
 238 that all other dependencies of the package (including dependencies on
 239 target architecture and MMU support) have to be repeated on the
 240 +comment+ definition. To keep it clear, the +depends on+ statement for
 241 these non-toolchain option should be kept separate from the +depends on+
 242 statement for the toolchain options.
 243 If there is a dependency on a config option in that same file (typically
 244 the main package) it is preferable to have a global +if ... endif+
 245 construct rather than repeating the +depends on+ statement on the
 246 comment and other config options.
 247
 248 The general format of a dependency +comment+ for package foo is:
 249
 250 --------------------------
 251 foo needs a toolchain w/ featA, featB, featC
 252 --------------------------
 253
 254 for example:
 255
 256 --------------------------
 257 mpd needs a toolchain w/ C++, threads, wchar
 258 --------------------------
 259
 260 or
 261
 262 --------------------------
 263 crda needs a toolchain w/ threads
 264 --------------------------
 265
 266 Note that this text is kept brief on purpose, so that it will fit on a
 267 80-character terminal.
 268
 269 The rest of this section enumerates the different target and toolchain
 270 options, the corresponding config symbols to depend on, and the text to
 271 use in the comment.
 272
 273 * Target architecture
 274 ** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+)
 275 ** Comment string: no comment to be added
 276
 277 * MMU support
 278 ** Dependency symbol: +BR2_USE_MMU+
 279 ** Comment string: no comment to be added
 280
 281 * Gcc +__sync_*+ built-ins used for atomic operations. They are
 282   available in variants operating on 1 byte, 2 bytes, 4 bytes and 8
 283   bytes. Since different architectures support atomic operations on
 284   different sizes, one dependency symbol is available for each size:
 285 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_SYNC_1+ for 1 byte,
 286    +BR2_TOOLCHAIN_HAS_SYNC_2+ for 2 bytes,
 287    +BR2_TOOLCHAIN_HAS_SYNC_4+ for 4 bytes, +BR2_TOOLCHAIN_HAS_SYNC_8+
 288    for 8 bytes.
 289 ** Comment string: no comment to be added
 290
 291 * Gcc +__atomic_*+ built-ins used for atomic operations.
 292 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_ATOMIC+.
 293 ** Comment string: no comment to be added
 294
 295 * Kernel headers
 296 ** Dependency symbol: +BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y+, (replace
 297    +X_Y+ with the proper version, see +toolchain/Config.in+)
 298 ** Comment string: +headers >= X.Y+ and/or `headers <= X.Y` (replace
 299    +X.Y+ with the proper version)
 300
 301 * GCC version
 302 ** Dependency symbol: +BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y+, (replace
 303    +X_Y+ with the proper version, see +toolchain/Config.in+)
 304 ** Comment string: +gcc >= X.Y+ and/or `gcc <= X.Y` (replace
 305    +X.Y+ with the proper version)
 306
 307 * Host GCC version
 308 ** Dependency symbol: +BR2_HOST_GCC_AT_LEAST_X_Y+, (replace
 309    +X_Y+ with the proper version, see +Config.in+)
 310 ** Comment string: no comment to be added
 311 ** Note that it is usually not the package itself that has a minimum
 312    host GCC version, but rather a host-package on which it depends.
 313
 314 * C library
 315 ** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+,
 316    +BR2_TOOLCHAIN_USES_MUSL+, +BR2_TOOLCHAIN_USES_UCLIBC+
 317 ** Comment string: for the C library, a slightly different comment text
 318    is used: +foo needs a glibc toolchain+, or `foo needs a glibc
 319    toolchain w/ C++`
 320
 321 * C++ support
 322 ** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+
 323 ** Comment string: `C++`
 324
 325 * D support
 326 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_DLANG+
 327 ** Comment string: `Dlang`
 328
 329 * Fortran support
 330 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_FORTRAN+
 331 ** Comment string: `fortran`
 332
 333 * thread support
 334 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+
 335 ** Comment string: +threads+ (unless +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
 336    is also needed, in which case, specifying only +NPTL+ is sufficient)
 337
 338 * NPTL thread support
 339 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
 340 ** Comment string: +NPTL+
 341
 342 * RPC support
 343 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+
 344 ** Comment string: +RPC+
 345
 346 * wchar support
 347 ** Dependency symbol: +BR2_USE_WCHAR+
 348 ** Comment string: +wchar+
 349
 350 * dynamic library
 351 ** Dependency symbol: +!BR2_STATIC_LIBS+
 352 ** Comment string: +dynamic library+
 353
 354 ==== Dependencies on a Linux kernel built by buildroot
 355
 356 Some packages need a Linux kernel to be built by buildroot. These are
 357 typically kernel modules or firmware. A comment should be added in the
 358 Config.in file to express this dependency, similar to dependencies on
 359 toolchain options. The general format is:
 360
 361 --------------------------
 362 foo needs a Linux kernel to be built
 363 --------------------------
 364
 365 If there is a dependency on both toolchain options and the Linux
 366 kernel, use this format:
 367
 368 --------------------------
 369 foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built
 370 --------------------------
 371
 372 ==== Dependencies on udev /dev management
 373
 374 If a package needs udev /dev management, it should depend on symbol
 375 +BR2_PACKAGE_HAS_UDEV+, and the following comment should be added:
 376
 377 --------------------------
 378 foo needs udev /dev management
 379 --------------------------
 380
 381 If there is a dependency on both toolchain options and udev /dev
 382 management, use this format:
 383
 384 --------------------------
 385 foo needs udev /dev management and a toolchain w/ featA, featB, featC
 386 --------------------------
 387
 388 ==== Dependencies on features provided by virtual packages
 389
 390 Some features can be provided by more than one package, such as the
 391 openGL libraries.
 392
 393 See xref:virtual-package-tutorial[] for more on the virtual packages.
 394
 395 === The +.mk+ file
 396
 397 [[adding-packages-mk]]
 398
 399 Finally, here's the hardest part. Create a file named +libfoo.mk+. It
 400 describes how the package should be downloaded, configured, built,
 401 installed, etc.
 402
 403 Depending on the package type, the +.mk+ file must be written in a
 404 different way, using different infrastructures:
 405
 406 * *Makefiles for generic packages* (not using autotools or CMake):
 407   These are based on an infrastructure similar to the one used for
 408   autotools-based packages, but require a little more work from the
 409   developer. They specify what should be done for the configuration,
 410   compilation and installation of the package. This
 411   infrastructure must be used for all packages that do not use the
 412   autotools as their build system. In the future, other specialized
 413   infrastructures might be written for other build systems. We cover
 414   them through in a xref:generic-package-tutorial[tutorial] and a
 415   xref:generic-package-reference[reference].
 416
 417 * *Makefiles for autotools-based software* (autoconf, automake, etc.):
 418   We provide a dedicated infrastructure for such packages, since
 419   autotools is a very common build system. This infrastructure 'must'
 420   be used for new packages that rely on the autotools as their build
 421   system. We cover them through a xref:autotools-package-tutorial[tutorial]
 422   and xref:autotools-package-reference[reference].
 423
 424 * *Makefiles for cmake-based software*: We provide a dedicated
 425    infrastructure for such packages, as CMake is a more and more
 426    commonly used build system and has a standardized behaviour. This
 427    infrastructure 'must' be used for new packages that rely on
 428    CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
 429    and xref:cmake-package-reference[reference].
 430
 431 * *Makefiles for Python modules*: We have a dedicated infrastructure
 432    for Python modules that use the +distutils+, +flit+, +pep517+ or
 433    +setuptools+ mechanisms. We cover them through a
 434    xref:python-package-tutorial[tutorial] and a
 435    xref:python-package-reference[reference].
 436
 437 * *Makefiles for Lua modules*: We have a dedicated infrastructure for
 438    Lua modules available through the LuaRocks web site. We cover them
 439    through a xref:luarocks-package-tutorial[tutorial] and a
 440    xref:luarocks-package-reference[reference].
 441
 442 Further formatting details: see xref:writing-rules-mk[the writing
 443 rules].
 444
 445 [[adding-packages-hash]]
 446 === The +.hash+ file
 447
 448 When possible, you must add a third file, named +libfoo.hash+, that
 449 contains the hashes of the downloaded files for the +libfoo+
 450 package. The only reason for not adding a +.hash+ file is when hash
 451 checking is not possible due to how the package is downloaded.
 452
 453 When a package has a version selection choice, then the hash file may be
 454 stored in a subdirectory named after the version, e.g.
 455 +package/libfoo/1.2.3/libfoo.hash+. This is especially important if the
 456 different versions have different licensing terms, but they are stored
 457 in the same file. Otherwise, the hash file should stay in the package's
 458 directory.
 459
 460 The hashes stored in that file are used to validate the integrity of the
 461 downloaded files and of the license files.
 462
 463 The format of this file is one line for each file for which to check the
 464 hash, each line with the following three fields separated by two spaces:
 465
 466 * the type of hash, one of:
 467 ** +md5+, +sha1+, +sha224+, +sha256+, +sha384+, +sha512+
 468 * the hash of the file:
 469 ** for +md5+, 32 hexadecimal characters
 470 ** for +sha1+, 40 hexadecimal characters
 471 ** for +sha224+, 56 hexadecimal characters
 472 ** for +sha256+, 64 hexadecimal characters
 473 ** for +sha384+, 96 hexadecimal characters
 474 ** for +sha512+, 128 hexadecimal characters
 475 * the name of the file:
 476 ** for a source archive: the basename of the file, without any directory
 477    component,
 478 ** for a license file: the path as it appears in +FOO_LICENSE_FILES+.
 479
 480 Lines starting with a +#+ sign are considered comments, and ignored. Empty
 481 lines are ignored.
 482
 483 There can be more than one hash for a single file, each on its own line. In
 484 this case, all hashes must match.
 485
 486 .Note
 487 Ideally, the hashes stored in this file should match the hashes published by
 488 upstream, e.g. on their website, in the e-mail announcement... If upstream
 489 provides more than one type of hash (e.g. +sha1+ and +sha512+), then it is
 490 best to add all those hashes in the +.hash+ file. If upstream does not
 491 provide any hash, or only provides an +md5+ hash, then compute at least one
 492 strong hash yourself (preferably +sha256+, but not +md5+), and mention
 493 this in a comment line above the hashes.
 494
 495 .Note
 496 The hashes for license files are used to detect a license change when a
 497 package version is bumped. The hashes are checked during the make legal-info
 498 target run. For a package with multiple versions (like Qt5),
 499 create the hash file in a subdirectory +<packageversion>+ of that package
 500 (see also xref:patch-apply-order[]).
 501
 502 The example below defines a +sha1+ and a +sha256+ published by upstream for
 503 the main +libfoo-1.2.3.tar.bz2+ tarball, an +md5+ from upstream and a
 504 locally-computed +sha256+ hashes for a binary blob, a +sha256+ for a
 505 downloaded patch, and an archive with no hash:
 506
 507 ----
 508 # Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
 509 sha1  486fb55c3efa71148fe07895fd713ea3a5ae343a  libfoo-1.2.3.tar.bz2
 510 sha256  efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369  libfoo-1.2.3.tar.bz2
 511
 512 # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
 513 md5  2d608f3c318c6b7557d551a5a09314f03452f1a1  libfoo-data.bin
 514 sha256  01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b  libfoo-data.bin
 515
 516 # Locally computed:
 517 sha256  ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9  libfoo-fix-blabla.patch
 518
 519 # Hash for license files:
 520 sha256  a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8  COPYING
 521 sha256  01b1f9f2c8ee648a7a596a1abe8aa4ed7899b1c9e5551bda06da6e422b04aa55  doc/COPYING.LGPL
 522 ----
 523
 524 If the +.hash+ file is present, and it contains one or more hashes for a
 525 downloaded file, the hash(es) computed by Buildroot (after download) must
 526 match the hash(es) stored in the +.hash+ file. If one or more hashes do
 527 not match, Buildroot considers this an error, deletes the downloaded file,
 528 and aborts.
 529
 530 If the +.hash+ file is present, but it does not contain a hash for a
 531 downloaded file, Buildroot considers this an error and aborts. However,
 532 the downloaded file is left in the download directory since this
 533 typically indicates that the +.hash+ file is wrong but the downloaded
 534 file is probably OK.
 535
 536 Hashes are currently checked for files fetched from http/ftp servers,
 537 Git or subversion repositories, files copied using scp and local files.
 538 Hashes are not checked for other version control systems (such as CVS,
 539 mercurial) because Buildroot currently does not generate reproducible
 540 tarballs when source code is fetched from such version control
 541 systems.
 542
 543 Additionally, for packages for which it is possible to specify a custom
 544 version (e.g. a custom version string, a remote tarball URL, or a VCS
 545 repository location and changeset), Buildroot can't carry hashes for
 546 those. It is however possible to xref:customize-hashes[provide a list of
 547 extra hashes] that can cover such cases.
 548
 549 Hashes should only be added in +.hash+ files for files that are
 550 guaranteed to be stable. For example, patches auto-generated by Github
 551 are not guaranteed to be stable, and therefore their hashes can change
 552 over time. Such patches should not be downloaded, and instead be added
 553 locally to the package folder.
 554
 555 If the +.hash+ file is missing, then no check is done at all.
 556
 557 [[adding-packages-start-script]]
 558 === The +SNNfoo+ start script
 559
 560 Packages that provide a system daemon usually need to be started somehow
 561 at boot.  Buildroot comes with support for several init systems, some
 562 are considered tier one (see xref:init-system[]), while others are also
 563 available but do not have the same level of integration.  Ideally, all
 564 packages providing a system daemon should provide a start script for
 565 BusyBox/SysV init and a systemd unit file.
 566
 567 For consistency, the start script must follow the style and composition
 568 as shown in the reference: +package/busybox/S01syslogd+. An annotated
 569 example of this style is shown below. There is no specific coding style
 570 for systemd unit files, but if a package comes with its own unit file,
 571 that is preferred over a buildroot specific one, if it is compatible
 572 with buildroot.
 573
 574 The name of the start script is composed of the +SNN+ and the daemon
 575 name.  The +NN+ is the start order number which needs to be carefully
 576 chosen.  For example, a program that requires networking to be up should
 577 not start before +S40network+.  The scripts are started in alphabetical
 578 order, so +S01syslogd+ starts before +S01watchdogd+, and +S02sysctl+
 579 start thereafter.
 580
 581 ------------------------------
 582 01: #!/bin/sh
 583 02:
 584 03: DAEMON="syslogd"
 585 04: PIDFILE="/var/run/$DAEMON.pid"
 586 05:
 587 06: SYSLOGD_ARGS=""
 588 07:
 589 08: # shellcheck source=/dev/null
 590 09: [ -r "/etc/default/$DAEMON" ] && . "/etc/default/$DAEMON"
 591 10:
 592 11: # BusyBox' syslogd does not create a pidfile, so pass "-n" in the command line
 593 12: # and use "-m" to instruct start-stop-daemon to create one.
 594 13: start() {
 595 14:     printf 'Starting %s: ' "$DAEMON"
 596 15:     # shellcheck disable=SC2086 # we need the word splitting
 597 16:     start-stop-daemon -b -m -S -q -p "$PIDFILE" -x "/sbin/$DAEMON" \
 598 17:             -- -n $SYSLOGD_ARGS
 599 18:     status=$?
 600 19:     if [ "$status" -eq 0 ]; then
 601 20:             echo "OK"
 602 21:     else
 603 22:             echo "FAIL"
 604 23:     fi
 605 24:     return "$status"
 606 25: }
 607 26:
 608 27: stop() {
 609 28:     printf 'Stopping %s: ' "$DAEMON"
 610 29:     start-stop-daemon -K -q -p "$PIDFILE"
 611 30:     status=$?
 612 31:     if [ "$status" -eq 0 ]; then
 613 32:             rm -f "$PIDFILE"
 614 33:             echo "OK"
 615 34:     else
 616 35:             echo "FAIL"
 617 36:     fi
 618 37:     return "$status"
 619 38: }
 620 39:
 621 40: restart() {
 622 41:     stop
 623 42:     sleep 1
 624 43:     start
 625 44: }
 626 45:
 627 46: case "$1" in
 628 47:     start|stop|restart)
 629 48:             "$1";;
 630 49:     reload)
 631 50:             # Restart, since there is no true "reload" feature.
 632 51:             restart;;
 633 52:     *)
 634 53:             echo "Usage: $0 {start|stop|restart|reload}"
 635 54:             exit 1
 636 55: esac
 637 ------------------------------
 638
 639 *Note:* programs that support reloading their configuration in some
 640 fashion (+SIGHUP+) should provide a +reload()+ function similar to
 641 +stop()+.  The +start-stop-daemon+ supports +-K -s HUP+ for this.
 642 It is recommended to always append +-x "/sbin/$DAEMON"+ to all the
 643 +start-stop-daemon+ commands to ensure signals are set to a PID that
 644 matches +$DAEMON+.
 645
 646 Both start scripts and unit files can source command line arguments from
 647 +/etc/default/foo+, in general, if such a file does not exist it should
 648 not block the start of the daemon, unless there is some site specirfic
 649 command line argument the daemon requires to start.  For start scripts a
 650 +FOO_ARGS="-s -o -m -e -args"+ can be defined to a default value in and
 651 the user can override this from +/etc/default/foo+.