doc/best-practices.md

   1 # oi-userland best practices
   2
   3 oi-userland build system is constantly evolving. So we tried to gather some 'best practices' for component's Makefiles and manifests.
   4
   5 1. Ugly is wrong. Complex is likely wrong.
   6
   7    If your Makefile becomes too complex or ugly, likely you are doing something wrong. Committer will more likely accept component, which logic it can understand,
   8 looking at Makefile without actually running build.
   9
  10 2. Try to use existing rule sets.
  11
  12    Each Makefile usually is based on one of the rule sets in make-rules - for example justmake.mk for simple Makefile-based software,
  13 configure.mk for autoconf-based components (sometimes it's used for autoconf-like components, for example components/web/nginx), cmake.mk for
  14 cmake-based components. If you see that rule set which you are using is not rather adequate, check if there's better rule set. Using cmake.mk based
  15 rules will likely allow you to create simpler Makefile for software, using cmake, than configure.mk. See rule 1.
  16
  17 3. Try to set common macros in Makefile, rather than in component's manifest.
  18
  19    Look for examples at templates/\<ruleset\>.mk. Almost all header field values
  20 can be set in Makefile. For simple components sample manifest, generated by 'gmake sample-manifest', and your p5m file will likely differ only in copyright line
  21 and perhaps some transform rules.
  22
  23 4. Hide complex software-specific installation logic in patches and artificial Makefiles.
  24
  25    Some software has installation logic, which is not suitable for us. Or just completely lacks it (for example, ships just some scripts).
  26 Usually it's better to correct this logic in patches. When it's completely missing, common pattern is to ship simple Makefile in
  27 $(COMPONENT_DIR)/files/Makefile and copy it to unpacked component archive in COMPONENT_PREP_ACTION.
  28 If it's easier to achieve desired layout by some transforms in manifests or specifying alternative file/link path in manifest than patch
  29 software to do 'the right thing', do it in manifest.
  30
  31 5. Prefer simplicity to generality.
  32
  33    Don't over-engineer. You create component, which will be used as part of oi-userland and only on OpenIndiana. Don't create knobs and whistles.
  34 Component is delivered to user in compiled form. Nobody will touch your knobs except the next person who would like to update component.
  35 The only exception to this rule concerns upstreamable patches, which possibly should be rather generic to be accepted.
  36
  37 6. Specify REQUIRED_PACKAGES in your component's Makefile.
  38
  39    For this you can do 'gmake REQUIRED_PACKAGES'. This allows other users to check that they have sane build environment.
  40
  41 7. Place component in corresponding [category](./categories-layout.md).
  42
  43    When in doubt, look at packages FMRIs.
  44
  45 8. If you can, provide COMPONENT_SIG_URL .
  46
  47    This allows everyone to check that tarball was not compromised. Also this helps with updating component - you can update COMPONENT_VERSION and
  48 tarball will not be removed because of wrong checksum. Nonetheless, update component's archive's checksums when necessary even when component
  49 has COMPONENT_SIG_URL set.
  50
  51 9. Provide sample-manifest, if it's not empty.
  52
  53    Always include manifests/sample-manifest.p5m in your PR. This simplifies component's updates (you can easily find out which files (dis)appeared
  54 and correct your p5m manifests just using 'git diff manifests/sample-manifest.p5m').
  55
  56 10. Format manifests similar to one, generated by sample-manifest.
  57
  58     Usually it includes items in the following order:
  59
  60        - copyright header (don't forget to update it, \<contributor\> can't be a copyright holder);
  61        - basic set actions (pkg.fmri, classification and so on, usually you don't touch generated part - see 3rd rule);
  62        - license action;
  63        - necessary transforms;
  64        - group and user actions;
  65        - file,link and other actions, which don't match those in sample-manifest (e.g. deliver configuration files from $(COMPONENT_DIR)/files directory);
  66        - necessary depend actions (if you can, use TBD 'fmri=__TBD' depend actions);
  67        - contents, generated by gmake sample-manifest.
  68
  69 11. Rule of three publishes.
  70
  71     Your component should be rebuilt and republished correctly, when its Makefile is touched. And almost always only when its Makefile is touched.
  72 So, when you touch Makefile, it should be reinstalled and republished on 'gmake publish'. If you run 'gmake publish' twice, it could be republished due to some
  73 peculiarities in publishing logic. If you run 'gmake publish' three times and component is republished, something is wrong with your Makefile.
  74
  75 12. Bump COMPONENT_REVISION when you change component.
  76
  77     It's the easiest way to trigger component's rebuild (see 11), and also it is reflected in packages' branch ids, so you can clearly find out which package version is installed.
  78 Usually initially you don't set it and it defaults to 0. On subsequent component changes you bump it. If COMPONENT_VERSION is updated, you should remove COMPONENT_REVISION.
  79
  80 13. Provide system integration when necessary.
  81
  82     The last thing everybody needs is to realize that after they install the package, they have no way how to run the service because it is missing (valid!) SMF manifest, RBAC profiles, desktop files, etc.
  83 To provide a certain quality, packages should be integrated with the system at least minimally.
  84
  85 14. Use test suites.
  86
  87     If component has check target, usually you can use its test suite automatically, adding test target to your component. If component has $(COMPONENT_DIR)/test/results-$(BITS).master, test output is compared
  88 to output in this file. You can perform sed/awk operations on test results, setting necessary operations in COMPONENT_TEST_TRANSFORMS. This allows to find regressions when component
  89 is modified. If test files do not exist already, create empty test files $(COMPONENT_DIR)/test/results-$(BITS).master to trigger the test comparison stage. If tests are identical for 32-bit and 64-bit builds, you can create a unique $(COMPONENT_DIR)/test/results-all.master.
  90
  91 15. Check if library updates are ABI compatible.
  92
  93     You can check for instance on https://abi-laboratory.pro/tracker/ for a selection of common libraries.
  94 Trigger rebuild of dependent components if necessary.
  95 List them, assuming that you are updating 'library/foo', with pkg search -r -o pkg.name 'depend:require:library/foo'.
  96
  97 16. When in doubt, look at existing components.
  98
  99 17. When in doubt and your question wasn't answered by taking a look at existing components, ask on IRC.
 100