diff --git a/docs/styleguide.md b/docs/styleguide.md new file mode 100644 index 000000000..53d156d68 --- /dev/null +++ b/docs/styleguide.md @@ -0,0 +1,198 @@ +Before you read this document, you should familiarize yourself with the upstream [yocto project styleguide](https://www.openembedded.org/wiki/Styleguide). meta-nilrt roughly follows the upstream guide, except where the rules in this document disagree. + + +# General + +**Capitalize NI LinuxRT and NILRT** + +When referring to "NI LinuxRT" in recipes and documentation, or its abbreviated form: "NILRT", capitalize the N-I-L-R-and-T. The exception to this rule is when speaking about the "meta-nilrt" layer itself, or the "nilrt" git repository - where it is recommended you call it "nilrt.git". + +**Indentation** + +Use **tabs** for indentation and **spaces** for alignment in all places - *except* within python task functions, where spaces should be used for both. + +The above policy differs from [yocto upstream's policy](https://www.openembedded.org/wiki/Styleguide#Format_Guidelines). Keep that in mind, if you are contributing both to meta-nilrt and to an upstream layer. + +**Multiline Variable Assignment** + +When recipe variables contain more than one *element*, the assignment should be written across multiple lines. This style greatly reduces the *noise* in git commits, and makes for easier rebases. + +Further, meta-nilrt prefers to use **tabs** for indentation and follow this style... + +``` +VARIABLE = "\ + value_one \ + value_two \ +" +``` + +The `DESCRIPTION` variable is generally exempt from these rules, since it is normally modified completely within git commits. + + +## Where to make recipe changes? + +OE recipe metadata is distributed across bitbake layers within the project, and it is generally important to the health of the distribution that recipe changes are made in the appropriate layers. + +If your recipe changes are appropriate for the OpenEmbedded community as a whole, they should be submitted to the appropriate community-layer upstream first. Once accepted by upstream, they should be cherry-picked back into the NI-owned fork of the layer. + +If your recipe changes are specific to NI LinuxRT, they should be made in the `meta-nilrt` layer. + +Keep in mind that it might be most-correct to split your patchset changes across layers, if part of the changes are OE-generic and part are NILRT-specific. + + +# Recipes + +## Recipe Names + +* Recipes should be named to match their upstream project name, unless it conflicts with an existing recipe. Recipes whose source is contained entirely within meta-nilrt can be freely named. +* Recipes which contain NI (National Instruments) content should be prefixed with `ni-`. eg. `ni-foobar.bb`. +* Recipe files whose source is contained entirely within meta-nilrt should *not* encode a package version in the recipe file name. Instead, they should explicitly declare a `PV` variable within the recipe. This rule allows the recipe version to be increased without introducing a rename into the git commit history. + ``` + ni-foobar.bb # good + ni-foobar_1.0.bb # bad + ``` + +## Layout + +When laying out the variables within a recipe `.bb` or `.bbappend` file, generally follow the styling recommended by the [yocto wiki styleguide](https://www.openembedded.org/wiki/Styleguide#Style_Guidelines). + +Recipe variables are generally divided into 6 sections, outlined below. +
+ +1. *Recipe Metadata* + * `SUMMARY` + * `DESCRIPTION` + * `AUTHOR` + * `HOMEPAGE` + * `BUGTRACKER` + * `SECTION` + * `LICENSE` + * `LIC_FILES_CHKSUM` +2. *Recipe Variables* + * `DEPENDS` + * `PROVIDES` + * `PV` +2. *Source Variables* + * `SRC_URI` + * `SRCREV` + * `S` +3. *Class Variables* + * `inherit ...` + * `PACKAGECONFIG` + * build class specific variables, i.e. `EXTRA_QMAKEVARS_POST`, `EXTRA_OECONF` +4. *Task Variables* + * task overrides, ie. `do_configure` +5. *Package Variables* + * `PACKAGEARCH` + * `PACKAGES` + * `FILES` + * `RDEPENDS` + * `RRECOMMENDS` + * `RSUGGESTS` + * `RPROVIDES` + * `RCONFLICTS` +6. *Class Extensions* + * `BBCLASSEXTEND` + +
+ +Contributors are free to use a single newline to create logical breaks between dissimilar variables *within* a section, and are encouraged to use double-newlines between each section. + + +## Variables + +### Metadata + +**BUGTRACKER** +* Set to the URL of the upstream project's bugtracker. + * If the recipe source lives in the meta-nilrt layer directly, do not set this variable. Users can infer that the bugtracker is the `HOMEPAGE` - which should be set to the meta-nilrt upstream. + +**DESCRIPTION** +* can be multiline. +* should describe the package in complete sentences. +* Prefer the expanded "NI LinuxRT" form, to maximize users' understanding. + +**HOMEPAGE** +* Set to the URL of the project upstream. + * If the recipe source lives in the meta-nilrt layer directly, set the homepage to the meta-nilrt canonical GH repo. `HOMEPAGE = "https://github.com/ni/meta-nilrt"` + +**SUMMARY** +* Limit SUMMARY to 80 characters. +* Prefer the abbreviated "NILRT" form, to conserve characters. + + +# .patch Files + +[Example of a good .patch file commit.](https://github.com/ni/meta-nilrt/pull/50/commits/73b046c57d73e188a3bf4adbf0965aa9312ebe08) + +`.patch` files should include the original author's commit message and meta information at their top. Information about the OE context (like why the `.patch` file is needed for the recipe) should be added after the original author's commit. + +At a minimum, you should add an additional message trailer declaring the [upstream status](https://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines#Patch_Header_Recommendations:_Upstream-Status) of the .patch file at the time of your OE commit. These status lines are crucial to helping the project maintainers properly upgrade and rebase recipes. Common status lines are: + +* `Upstream-Status: Inappropriate [$rationale]` ([ex](https://github.com/ni/meta-nilrt/blob/nilrt/master/sumo/recipes-support/curl/curl/0005-Add-nicurl-wrapper-functions.patch)) For when the `.patch` change is specific to NI LinuxRT and would not be desired (or has been rejected) by upstream. +* `Upstream-Status: Not Submitted [$rationale]` ([ex](https://github.com/ni/meta-nilrt/blob/nilrt/master/sumo/recipes-gnome/florence/files/0004-Add-option-for-automatic-bring-to-top.patch)) For when the `.patch` file is being included in NILRT before being submitted to its upstream project. This should only occur if the `.patch` is needed for an immediate NILRT release and there is no time to get it reviewed upstream beforehand. Or if - as in the case of the example - the upstream repo is dead. +* `Upstream-Status: Submitted [$upstream_link]` ([ex](https://github.com/ni/meta-nilrt/blob/1e6453ebca8735de96eaaf3bc931d22998c8dfb3/recipes-support/curl/curl/0014-Fixup-lib1529-test.patch)) For when the `.patch` has been submitted to the upstream project by mailing list or merge PR, but needs to be pulled into NILRT prior to final upstream approval. +* `Upstream-Status: Accepted [$upstream_link]` ([ex](https://github.com/ni/meta-nilrt/blob/904bd00bf24d8fe61d3a13b8ece368c9741a73fc/recipes-devtools/opkg/files/0002-libopkg-clear-curl-properties-on-download-error-to-p.patch#L36)) For when the `.patch` has been approved and pulled by the upstream project. + + +#### .patch file names + +When bitbake applies `.patch` files to a recipe, it copies all `.patch` files into the recipe's workspace, then applies them in alphanumeric-order. In your PR, be mindful of how your `.patch` file is ordered versus the other files in the recipe. Keep in mind that some `.patch` files might come from other layers. + + +# Example Recipe +This is an example recipe for a package whose source is contained in the meta-nilrt layer. + +`.../foobar/` +``` +foobar/ +|- files/ +| |- foo-file.1 +| |- foo-file.2 +| \- foo.initd +\- foobar.bb +``` +---- +`.../foobar/foobar.bb` +``` +SUMMARY = "foobar - The example project" +DESCRIPTION = "\ +foobar is an example project, used when you need to communicate concepts to \ +developers." +HOMEPAGE = "https://github.com/ni/meta-nilrt" +SECTION = "test" +LICENSE = "MIT" +LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" + + +PV = "1.0" + + +SRC_URI = "\ + file://foo-file.1 \ + file://foo-file.2 \ + file://foo.initd \ +" + +S = "${WORKDIR}" + + +inherit update-rc.d +INITSCRIPT_PARAMS = "default" +INITSCRIPT = "foo" + + +prefix_lib=${libdir}/${BPN} + +do_install () { + install -d ${D}${sysconfdir}/init.d + install foo.initd ${D}${sysconfdir}/init.d/foo + + install -d ${D}${prefix_lib} + install --mode=0755 foo-file.1 ${D}${prefix_lib}/foo-file.1 + install --mode=0744 foo-file.2 ${D}${prefix_lib}/foo-file.2 +} + + +RDEPENDS:${PN} = "bash" +``` \ No newline at end of file