diff options
Diffstat (limited to 'doc/packaging.cli')
| -rw-r--r-- | doc/packaging.cli | 134 |
1 files changed, 112 insertions, 22 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli index 5e8cb53..6b1fdb5 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -1500,14 +1500,15 @@ the project-wide build system files in \c{build/} and the source subdirectory \c{buildfiles} (in \c{include/} and \c{src/} for our \c{libfoo} example). -\h2#core-adjust-build-wide|Review project-wide build system files in \c{build/}| +\h2#core-adjust-build-wide|Adjust project-wide build system files in \c{build/}| -We start with reviwing the files in the \c{build/} subdirectory of our -package, where you will find three files: \c{bootstrap.build}, \c{root.build}, -and \c{export.build}. To recap, the first two contain the project-wide build -system setup (see \l{b#intro-proj-struct Project Structure} for details) while -the last is an export stub that facilitates the importation of targets from -our package (see \l{b#intro-import Target Importation} for details). +We start with reviwing and adjusting the files in the \c{build/} subdirectory +of our package, where you will find three files: \c{bootstrap.build}, +\c{root.build}, and \c{export.build}. To recap, the first two contain the +project-wide build system setup (see \l{b#intro-proj-struct Project Structure} +for details) while the last is an export stub that facilitates the importation +of targets from our package (see \l{b#intro-import Target Importation} for +details). Normally you don't need to change anything in \c{bootstrap.build} \- all it does is specify the build system project name and load a standard set of core @@ -1860,7 +1861,7 @@ Linked Configurations} on how to handle that. In this case you will also need to reconfigure your package after adding the corresponding \c{import} directives in order to re-acquire the previously dropped \c{config.import.*} values. Make sure to also pass any configuration variables you specified in -\l{#core-adjust-build-wide Review project-wide build system files in +\l{#core-adjust-build-wide Adjust project-wide build system files in \c{build/}}. For example: \ @@ -1959,7 +1960,7 @@ background on wildcard patterns). If your C++ package doesn't have any inline or template files, then you can remove the \c{ixx} and \c{txx} target types, respectively (which is parallel -to the change made in \c{root.build}; see \l{#core-adjust-build-wide Review +to the change made in \c{root.build}; see \l{#core-adjust-build-wide Adjust project-wide build system files in \c{build/}}). For example: \ @@ -2433,11 +2434,11 @@ turning into a smoke test. The subproject root \c{buildfile} rarely needs changing. -\h2#core-test-smoke-build-wide|Review project-wide build system files in \c{tests/build/}| +\h2#core-test-smoke-build-wide|Adjust project-wide build system files in \c{tests/build/}| -Review the generated \c{bootstrap.build} and \c{root.build} (there will be no -\c{export.build}) similar to \l{#core-adjust-build-wide Review project-wide -build system files in \c{build/}}. +Review and adjust the generated \c{bootstrap.build} and \c{root.build} (there +will be no \c{export.build}) similar to \l{#core-adjust-build-wide Adjust +project-wide build system files in \c{build/}}. Here the only change you would normally make is in \c{root.build} to drop the assignment of extensions for target types that are not used in tests. @@ -3501,18 +3502,107 @@ version is tagged \c{v2.1.0} and the new version is tagged \c{v2.2.0}: \ $ cd upstream -$ gitk& +$ gitk v2.1.0..v2.2.0 & \ -Then scroll down and click on the commit tagged \c{v2.1.0}, scroll up and -righ-click on the commit tagged \c{v2.2.0} and select the \"Diff this -> -selected\" menu item. This will display a cumulative set of changes between -the two upstream versions. Look through them for the following types of -changes: +Then click on the commit tagged \c{v2.2.0}, scroll down and right-click on the +commit tagged \c{v2.1.0}, and select the \"Diff this -> selected\" menu item. +This will display the cumulative set of changes between these two upstream +versions. Review them looking for the following types of changes in +particular (discussed in the following sections): -- changes to the source code layout -- new source files beging added or removed -- changes to the upstream build system +\ul| + +\li|Changes to the source code layout.| + +\li|New dependencies being added or old removed.| + +\li|New source files beging added or old removed (including in tests, etc).| + +\li|Changes to the upstream build system.| + +\li|Other new files/subdirectories being added or old removed.|| + + +\h2#core-version-management-new-version-layout|New version: layout changes| + +As mentioned earlier, for drastic layout changes it may make sense to start +from scratch and re-generate the package with the \c{bdep-new} command +(\l{#core-package-struct Decide on the package source code layout} starting +point). On the other hand, if the changes are minor, then you can try to +adjust things manually. An in-between strategy is to generate the new layout +using \c{bdep-new} on the side and then retrofit the relevant changes in +\c{buildfiles} to the existing package. In a sense, this approach uses +\c{bdep-new} as a guide to figure out how to implement the new layout. + + +\h2#core-version-management-new-version-dependecies|New version: new/old dependencies| + +If upsream added new or removed old dependecies, then you will need to +replicate these changes in your package as on the \l{#core-fill-depend Add +dependencies} and \l{#core-adjust-build-src-source-dep Adjust source +\c{buildfile}: dependencies} initial packaging steps. + + +\h2#core-version-management-new-version-sources|New version: new/old source files| + +If upsream added new or removed old source files, then you will need to +replicate these changes in your package as on the \c{#core-fill-source Fill +with upstream source code} and possibly \c{#core-adjust-build-src-header +Adjust header \c{buildfile}} and \l{#core-adjust-build-src-source-src Adjust +source \c{buildfile}: sources, private headers} initial packaging steps. + +Also don't forget about tests, examples, etc., which may also add new or +remove old source files (typically new tests). See +\l{#core-test-upstream-convert Convert smoke test to upstream tests}. + + +\h2#core-version-management-new-version-build|New version: changes to build system| + +If upsream changed anything in the build system, then you may need to +replicate these changes in your package's \c{buildfiles}. The relevant initial +packaging steps are: \l{#core-adjust-build-wide Adjust project-wide build system files in +\c{build/}} and \l{#core-adjust-build-src-source-opt Adjust source +\c{buildfile}: build and export options}. + +The corresponding steps for tests are: \l{#core-test-smoke-build-wide Adjust +project-wide build system files in \c{tests/build/}} and +\l{#core-test-upstream-convert Convert smoke test to upstream tests}. + + +\h2#core-version-management-new-version-other|New version: other new/old files/subdirectories| + +If upsream added or removed any other files or subdirectories that are +relevant to our package (such as documentation), then adjust the package +similar to the \l{#core-root-buildfile Adjust root \c{buildfile}} and +\l{#core-root-buildfile-doc Adjust root \c{buildfile}: other subdirectories} +initial packaging steps. + + +\h2#core-version-management-new-version-test|New version: test locally and with CI| + +Once all the adjustments are in, test the package both locally and with CI +similart to how we did after completing the smoke test during the initial +packaging: + +\l{#core-test-smoke-locally Test locally}\n +\l{#core-test-smoke-locally-install Test locally: installation}\n +\l{#core-test-smoke-locally-dist Test locally: distribution}\n +\l{#core-test-smoke-ci Commit and test with CI} + + +\h2#core-version-management-new-version-release|New version: merge, release, and publish| + +When the new version of the package is ready to be released, merge the +work branch to \c{master}: + +\ +$ git checkout master +$ git merge --ff-only wip-2.2.0 +\ + +Then release and publish using the same steps as after the initial packaging: +\l{#core-release-publish Release and publish}. @@ Maybe in the initial instructions makes sense to identify and note |