From c287cbe9e7db933835da282a4fe1ba1c76bc6a6f Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Sun, 29 Sep 2024 18:56:01 +0200 Subject: [PATCH 01/17] initial version Co-authored-by: sebix --- Tools/Sailfish_SDK/OBS_Packaging/README.md | 278 +++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 Tools/Sailfish_SDK/OBS_Packaging/README.md diff --git a/Tools/Sailfish_SDK/OBS_Packaging/README.md b/Tools/Sailfish_SDK/OBS_Packaging/README.md new file mode 100644 index 00000000..78d718b8 --- /dev/null +++ b/Tools/Sailfish_SDK/OBS_Packaging/README.md @@ -0,0 +1,278 @@ +--- +title: Packaging Software on OBS +permalink: Tools/Sailfish_SDK/OBS_Packaging +parent: Sailfish SDK +layout: default +nav_order: 400 +--- + +This page deals specifically with building packages using the [Open Build Service](/Services/Development/Open_Build_Service) instance. + +This requires the user to create a home project, and then create a package +under that project, with the appropriate `_service` file to specify how the +project should be built and packaged. Once the build has been triggered, OBS +will attempt to pull in the required dependencies and build the package. + +## Setting up the (Home) Project + +To create an account on OBS, follow the instructions on [the Chum help page](https://github.com/sailfishos-chum/main#user-content-submitting-actively-maintained-software). + +After creating a user account you are automatically the owner of the so-called "Home Project" named `home:$username`. +You can create various packages in that project and also create sub-projects. + +## Adding a Package + +Click "Create Package" in your project if using the Web Interface, or `osc mkpac mypackage` if using `osc`. + +## Adding the sources + +There are about three common "packaging formats" used in Sailfish OS development, which are described under [Packaging Formats](https://docs.sailfishos.org/Tools/Sailfish_SDK/Building_packages/#packaging-formats): + + - Plain Tarball + - "Application Repository": `tar_git` with source code repository + - "Packaging Repository": `tar_git` with upstream submodule + +A packaging repository is a git repository which contains just the build +instructions and some other files (like patches) to package software for +Sailfish OS, with the actual source code living in a git submodule of this +repository. + +### Plain Tarball sources + +Usually, nothing special needs to be done if you want to build software from a source tarball. + +You just populate the OBS package source like this: + +``` + application.spec + application-1.2.3.tar.gz +``` + +OBS will pick up both and run the build. + +To get the source information into OBS, either upload them using the Web Interface, or use the `osc` tool: + +``` +cd my:project:mypackage +cp /path/to/mypackage.tar.bz2 . +cp /path/to/mypackage.spec . +osc add * +osc commit +``` + +### `tar_git` sources + +`tar_git` is a OBS Service which clones a repository from a public git hoster, +creates a tarball from it, extracts the build information, and places all those +files into the OBS Package source location. + +To get the service configured on OBS, create a file called `_service` with the following content: +``` + + + https://github.com/orgname/reponame.git + + + + N + N + + +``` + +and then either upload them using the Web Interface, or use the `osc` tool: +``` +osc mkpac mypackage # create a new OBS package +cd mypackage +cp /path/to/_service . +osc add _service +osc commit +``` + + +#### Understanding version mangling performed by `tar_git` + +Before starting the build process, OBS will perform certain changes to the +cloned .spec file. This mainly affects the contents of the `%{version}` and +`%{revision}` macros. + +For some examples, see below. + +`%specialversion` will consist of: + - if a tag parameter was specified in the `_service`, it will be used as the version + - if a branch parameter was specified in the `_service`, it will be appended to the name, along with the hash of the git ref, prepended by the letter "g". + - if no tag parameter was specified in the `_service`, but a branch name was, it will contain the value of the *latest* tag in the branch, and the branch name, timestamp, and git ref hash appended to it. + +`%specialrevision` will have the format X.Y.Z where: + - X is always 1 + - Y is a counter that roughly corresponds to the number of revisions of the OBS package source. + - Z is a counter starting at 1 and increasing each time OBS decides to automatically rebuild the package (usually because a dependency was rebuilt or newly published) + +Note that these auto-generated revision and version parameters will replace the +`%version` and `%revision` macros in the spec file throughout the OBS build +process. So you cannot use literal version or revision contents in your build +setup. If you need those, you should parse `%version` and `%revision`. + + +#### Understanding the source structure and tarballs generated by `tar_git` + +The tarball produced by the service has the following properties: + + - it will be named `_service:tar_git:%{name}-%{specialversion}-%{specialrevision}.tar.bz2` (see above about the `special` variables) + - it will contain a directory `%{name}-%{specialversion}-%{specialrevision}` + - the directory will: + - contain the content of the repository, but will not include the `.git` directory (so any git calls in your build process will not function). + - contain clones of all submodules (usually the "upstream" submodule), also without `.git` + - the same applies to submodules within submodules. + +The service will also extract `rpm` sub-directory from the source repo and place its contents in the OBS package root. +So the root may end up looking like this: + +``` + _service + _service:tar_git:foo-1.2+git3.tar.bz2 + _service:tar_git:foo.spec + _service:tar_git:foo.changes + _service:tar_git:foo-patchbar.diff +``` + + +**Some Examples** + + - url: https://github.com/orgname/foo.git + - branch: development + - revision: *empty* + +`_service:tar_git:foo-2.1+development.20240215221650.74.g0773230.tar.bz2` if the development branch contains a tag called 2.1 + + - url: https://github.com/orgname/foo.git + - branch: development + - revision: 2.2 + +`_service:tar_git:foo-2.2+development.20240215221650.74.g0773230.tar.bz2` + + - url: https://github.com/orgname/foo.git + - branch: *empty* + - revision: 2.2+git3 + +`_service:tar_git:foo-2.2+git3.tar.bz2` + + +#### Adjust the %setup macro parameters and other paths + +The name of the tarball must be the first `Source:` line in the .spec file. + +You should name it +``` +Source: %{name}-%{version}.tar.bz2 +``` + +You can choose a literal string as the name, but you must use the `%{version}` macro. + +(Note that `tar_git` will pick up the compression format you want to use from the extension, and will create the tarball accordingly.) + +**If you are building a "Packaging Repository"** + +Because of the structure of the tarball explained above, usually the `%prep` +section of .spec files will have to be adjusted to use the submodule directory +as the main source. + +So if the upstream submodule is called "upstream", the line should look like + +``` +%prep +%setup -q -n %{name}-%{version}/upstream +``` +You can choose a literal string as the name, but you must use the `%{version}` macro. + +Similarly, if you change working directories in the build process, be aware of where the actual source code is located relative to `%{_builddir}`: + +`%{_builddir}/%{name}-%{version}/upstream` + +On the other hand, the contents of the `rpm` sub-directory will be in the +package root, not under `rpm` during the build. Usually, this does not affect you +though, as OBS sets the `%{_sourcedir}` macro accordingly, so things like +`%SOURCE2` will work as intended. + +#### Adjust the build requirements (BuildRequires). + +The building service runner setup used on OBS is more bare-bones than the one +used in the Sailfish SDK, also with regard to the pre-installed packages. If +you are adapting a .spec file coming from a project developed in the SDK, it is +likely you are missing some build requirements even though the package compiled +fine under the SDK. + +Typically this involves the Qt dependencies, so you will need to add lines like the following: + +``` +BuildRequires: pkgconfig(Qt5Qml) +BuildRequires: pkgconfig(Qt5Quick) +BuildRequires: pkgconfig(Qt5Widgets) +BuildRequires: pkgconfig(Qt5Xml) +``` + +### Common errors + +Whenever you encounter an error and have attempted to remedy it, run either +`osc service rr` from the locally checked out OBS package, or "Trigger +Services" from the Web Interface. + +**ERROR: no packaging in this git clone** + +Your project does either not contain a spec file in the `rpm` directory. + +**ERROR: couldn't clone foo** + +Check the `url` parameter in the `_service` file. +Also, check the settings on your git host. The repository may be set to private. +And be sure to use a clone URL, not a web view of the repo (like git-web). + +``` + https://github.com/sailfishos-chum/qt6.git + gcc +``` + +**ERROR: Need single spec file in rpm** + +Your project does contain a directory called `rpm`, but that directory contains more than one .spec file, so `tar_git` gets confused. + +There are three possible solutions for that. + + 1. delete one of the .spec files in the repo ;) + 1. name the OBS package or the spec file so their names match exactly. `tar_git` will accept a spec file that has the same name as the project. + + Note that if you actually want to build all the spec files, you can either use OBS Links (`_link`), or `_multibuild` files to achieve that. + Either create links that correspond to the names of the other spec files or create a `_multibuild` file using the spec file names as `flavor`: + +``` + + foo + bar + +``` +**ERROR: couldn't determine version from spec file** + +Something is fishy about the `Version:` line in the .spec, or it is missing completely + +**ERROR: Source filename in .spec must end in .tar.gz, .tgz, .tar.bz2 or .tar.xz** + +The (first) `Source:` or `SourceX:` line in your .spec file is malformed. Be +sure to use one of the file extensions mentioned in the error message. + +**Unresolvable: nothing Provides foo** + +This is related to `BuildRequires:` in the .spec file. + +Reasons include: + + - The dependency is not available in the OBS repositories you have configured in the OBS Project's `meta` configuration. + - The dependency is available, but does not meet version requirements + +If your BuildRequires: uses something like `pkgconfig()` or `qml()`, try if +specifying the RPM package name (usually `package-devel`) helps. If it does, file an issue with the +package maintainer to include proper RPM `Provides` metadata. + +**Blocked: downloading 1 dod packages** + +This is a rare error which means one of the build dependencies is known to the OBS system, but the package can not be accessed for the builder to install. +You can not fix this yourself, you have to report this to the OBS maintainers. From 7b74050191fc41e7ba2093b360a9f7d57818751a Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:05:23 +0200 Subject: [PATCH 02/17] Some improvements and explanations --- Tools/Sailfish_SDK/OBS_Packaging/README.md | 71 ++++++++++++++++------ 1 file changed, 54 insertions(+), 17 deletions(-) diff --git a/Tools/Sailfish_SDK/OBS_Packaging/README.md b/Tools/Sailfish_SDK/OBS_Packaging/README.md index 78d718b8..f1c6b060 100644 --- a/Tools/Sailfish_SDK/OBS_Packaging/README.md +++ b/Tools/Sailfish_SDK/OBS_Packaging/README.md @@ -13,6 +13,16 @@ under that project, with the appropriate `_service` file to specify how the project should be built and packaged. Once the build has been triggered, OBS will attempt to pull in the required dependencies and build the package. +You can interact with the OBS either on the web interface at [https://build.sailfishos.org](https://build.sailfishos.org), or use the command-line tool, [osc](https://en.opensuse.org/openSUSE:OSC) + +**A note about terminology** + +*There are some terms, like "repository", "source", "package" that are used +both in the context of OBS, or in a general sense, and may have different +meanings depending on context. For example "repo" can mean either a build +environment configuration on OBS, or it's corresponding published RPM +repository. But it can also refer to a git repository.* + ## Setting up the (Home) Project To create an account on OBS, follow the instructions on [the Chum help page](https://github.com/sailfishos-chum/main#user-content-submitting-actively-maintained-software). @@ -20,7 +30,9 @@ To create an account on OBS, follow the instructions on [the Chum help page](htt After creating a user account you are automatically the owner of the so-called "Home Project" named `home:$username`. You can create various packages in that project and also create sub-projects. -## Adding a Package +See the official OBS [Beginnerʼs Guide](https://openbuildservice.org/help/manuals/obs-user-guide/art-obs-bg) for an introduction to OBS in general. + +## Creating an OBS Package Click "Create Package" in your project if using the Web Interface, or `osc mkpac mypackage` if using `osc`. @@ -35,7 +47,8 @@ There are about three common "packaging formats" used in Sailfish OS development A packaging repository is a git repository which contains just the build instructions and some other files (like patches) to package software for Sailfish OS, with the actual source code living in a git submodule of this -repository. +repository. +An "Application Repository" contains the source code itself, e.g. because you wrote it or cloned a third-party git repository. ### Plain Tarball sources @@ -44,8 +57,8 @@ Usually, nothing special needs to be done if you want to build software from a s You just populate the OBS package source like this: ``` - application.spec - application-1.2.3.tar.gz +application.spec +application-1.2.3.tar.gz ``` OBS will pick up both and run the build. @@ -59,13 +72,14 @@ cp /path/to/mypackage.spec . osc add * osc commit ``` - ### `tar_git` sources `tar_git` is a OBS Service which clones a repository from a public git hoster, creates a tarball from it, extracts the build information, and places all those files into the OBS Package source location. +You may look at its [source code](https://github.com/MeeGoIntegration/obs-service-tar-git) detailed information. + To get the service configured on OBS, create a file called `_service` with the following content: ``` @@ -82,14 +96,12 @@ To get the service configured on OBS, create a file called `_service` with the f and then either upload them using the Web Interface, or use the `osc` tool: ``` -osc mkpac mypackage # create a new OBS package -cd mypackage +cd my:project:mypackage cp /path/to/_service . osc add _service osc commit ``` - #### Understanding version mangling performed by `tar_git` Before starting the build process, OBS will perform certain changes to the @@ -108,11 +120,23 @@ For some examples, see below. - Y is a counter that roughly corresponds to the number of revisions of the OBS package source. - Z is a counter starting at 1 and increasing each time OBS decides to automatically rebuild the package (usually because a dependency was rebuilt or newly published) -Note that these auto-generated revision and version parameters will replace the +These auto-generated revision and version parameters will replace the `%version` and `%revision` macros in the spec file throughout the OBS build process. So you cannot use literal version or revision contents in your build setup. If you need those, you should parse `%version` and `%revision`. +(*Note: `%specialversion` and `%specialrevision` are not real macros, they are used here as examples only*) + +**About tagging** + +It is common practice to leverage the rules above and use git tags as version +specifiers. This is especially true for "Packaging Repositories", where tags +like `X.Y.Z+gitN` signify version `X.Y.Z` of the upstream software, and N the +iteration in the packaging repository. + +Be aware though that the parser above is not perfect. Also, some characters are +disallowed to appear in RPM version strings. So be conservative in the naming +of your tags. #### Understanding the source structure and tarballs generated by `tar_git` @@ -136,6 +160,13 @@ So the root may end up looking like this: _service:tar_git:foo-patchbar.diff ``` +**A note about "dumb" packages:** +*You notice there is a "dumb" parameter in the service confifuration. Setting +this to true switches the behaviour of the service to assume a very flat source +structure, and not generate a tarball. +You may use this if your sources are very simple, for example contain only a +single source code file and a Makefile, without any directory structure.* + **Some Examples** @@ -190,9 +221,9 @@ Similarly, if you change working directories in the build process, be aware of w `%{_builddir}/%{name}-%{version}/upstream` On the other hand, the contents of the `rpm` sub-directory will be in the -package root, not under `rpm` during the build. Usually, this does not affect you -though, as OBS sets the `%{_sourcedir}` macro accordingly, so things like -`%SOURCE2` will work as intended. +package root, not under `rpm` or `%_topdir/SOURCES` during the build. Usually, +this does not affect you though, as OBS sets the internal source path +accordingly, so things like `%SOURCE2` will work as expected. #### Adjust the build requirements (BuildRequires). @@ -213,13 +244,12 @@ BuildRequires: pkgconfig(Qt5Xml) ### Common errors -Whenever you encounter an error and have attempted to remedy it, run either -`osc service rr` from the locally checked out OBS package, or "Trigger -Services" from the Web Interface. +To retry after fixong an error, run either `osc service rr` from the locally +checked out OBS package, or "Trigger Services" from the Web Interface. **ERROR: no packaging in this git clone** -Your project does either not contain a spec file in the `rpm` directory. +Your project does not contain a spec file in the `rpm` directory. **ERROR: couldn't clone foo** @@ -232,6 +262,12 @@ And be sure to use a clone URL, not a web view of the repo (like git-web). gcc ``` +*Note: sometimes, if you tried to run the service against a non-public git +repo, failed, and later set the repo to public and try again, the service will +still fail with the same error. You will need to seek assistance from the OBS +maintainers in that case. +See also [this bug](https://github.com/MeeGoIntegration/obs-service-tar-git/issues/3). + **ERROR: Need single spec file in rpm** Your project does contain a directory called `rpm`, but that directory contains more than one .spec file, so `tar_git` gets confused. @@ -274,5 +310,6 @@ package maintainer to include proper RPM `Provides` metadata. **Blocked: downloading 1 dod packages** -This is a rare error which means one of the build dependencies is known to the OBS system, but the package can not be accessed for the builder to install. +This is a rare error which means one of the build dependencies is known to the +OBS system, but the package can not be accessed for the builder to install. You can not fix this yourself, you have to report this to the OBS maintainers. From 89ac16d28b49879051b80f1c914fc96c89cfe7a2 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:38:17 +0200 Subject: [PATCH 03/17] Add section about publishing --- Tools/Sailfish_SDK/OBS_Packaging/README.md | 58 ++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/Tools/Sailfish_SDK/OBS_Packaging/README.md b/Tools/Sailfish_SDK/OBS_Packaging/README.md index f1c6b060..a9479871 100644 --- a/Tools/Sailfish_SDK/OBS_Packaging/README.md +++ b/Tools/Sailfish_SDK/OBS_Packaging/README.md @@ -313,3 +313,61 @@ package maintainer to include proper RPM `Provides` metadata. This is a rare error which means one of the build dependencies is known to the OBS system, but the package can not be accessed for the builder to install. You can not fix this yourself, you have to report this to the OBS maintainers. + +## Publishing packages + +Once you have successfully built your package, you may want to test it. + +You can download the build results if you are logged into your account in the +Web Interface, or use `osc getbinaries`. + +Another approach is to publish the RPM repository for your project. Publishing +makes all packages available in a repository that can be used by tools like +`zypper` or `pkcon`, and managed by `ssu`. +Note however there is no access control over such published repositories, and +you can't know who will download your packages. This may or may not be what you want. + +To "properly" make your package available to the world, you are encouraged to +[submit your package to Chum](https://github.com/sailfishos-chum/main#user-content-submitting-actively-maintained-software). + + +To publish a package, either use the graphical tool in the Web Interface, or edit the Meta information. + +Not that Meta can be set globally or a Project, and then overridden per-package. + +With `osc`, the commands are: `osc meta -e prj`, and `osc meta -e pkg` + + +**Example Project Meta configuration:** + +Support x64, arm, arm64, build for both arm and arm64, but only publish arm64: + +``` + + Foo + The Foo suite of software + + + + + + + + + + + + + + i586 + + + + armv8el + + + + aarch64 + + +``` From 349a2519a28a5514209bdade057ec2fd27859040 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:39:31 +0200 Subject: [PATCH 04/17] Restucture, and clarify in places --- Tools/Sailfish_SDK/OBS_Packaging/README.md | 29 +++++++++++++--------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/Tools/Sailfish_SDK/OBS_Packaging/README.md b/Tools/Sailfish_SDK/OBS_Packaging/README.md index a9479871..f1c3887c 100644 --- a/Tools/Sailfish_SDK/OBS_Packaging/README.md +++ b/Tools/Sailfish_SDK/OBS_Packaging/README.md @@ -17,13 +17,12 @@ You can interact with the OBS either on the web interface at [https://build.sail **A note about terminology** -*There are some terms, like "repository", "source", "package" that are used -both in the context of OBS, or in a general sense, and may have different -meanings depending on context. For example "repo" can mean either a build -environment configuration on OBS, or it's corresponding published RPM -repository. But it can also refer to a git repository.* +*Some terms, like "repository", "source", "package", have different meanings +depending on context. For example "repo" can mean either a build environment +configuration on OBS, or it's corresponding published RPM repository. But it +can also refer to a git repository.* -## Setting up the (Home) Project +## Setting up the (Home) Project and creating a Package To create an account on OBS, follow the instructions on [the Chum help page](https://github.com/sailfishos-chum/main#user-content-submitting-actively-maintained-software). @@ -32,9 +31,7 @@ You can create various packages in that project and also create sub-projects. See the official OBS [Beginnerʼs Guide](https://openbuildservice.org/help/manuals/obs-user-guide/art-obs-bg) for an introduction to OBS in general. -## Creating an OBS Package - -Click "Create Package" in your project if using the Web Interface, or `osc mkpac mypackage` if using `osc`. +Click "Create Package" in your project if using the Web Interface, or `osc mkpac mypackage` if using `osc` to get started. ## Adding the sources @@ -61,7 +58,7 @@ application.spec application-1.2.3.tar.gz ``` -OBS will pick up both and run the build. +OBS will pick up both and run the build. No `_service` file is necessary in this case. To get the source information into OBS, either upload them using the Web Interface, or use the `osc` tool: @@ -72,6 +69,12 @@ cp /path/to/mypackage.spec . osc add * osc commit ``` + +*Note: Using a plain tarball is an convenient and quick way to package software +on OBS. Still, you are encouraged to move to a "Packaging Repo" approach for +various reasons, including better revision control and history, easier forking +by others, and backup/restore considerations.* + ### `tar_git` sources `tar_git` is a OBS Service which clones a repository from a public git hoster, @@ -161,7 +164,7 @@ So the root may end up looking like this: ``` **A note about "dumb" packages:** -*You notice there is a "dumb" parameter in the service confifuration. Setting +*You notice there is a "dumb" parameter in the service configuration. Setting this to true switches the behaviour of the service to assume a very flat source structure, and not generate a tarball. You may use this if your sources are very simple, for example contain only a @@ -242,7 +245,9 @@ BuildRequires: pkgconfig(Qt5Widgets) BuildRequires: pkgconfig(Qt5Xml) ``` -### Common errors +==== + +## Common errors To retry after fixong an error, run either `osc service rr` from the locally checked out OBS package, or "Trigger Services" from the Web Interface. From c5b9186f2ebbdb5e67b9e8b418069186421da5c1 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:46:44 +0200 Subject: [PATCH 05/17] Move document to another section: Tools/Sailfish_SDK/OBS_Packaging -> Services/Development/Open_Build_Service/Packaging_for_OBS --- .../Development/Open_Build_Service/Packaging_for_OBS}/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {Tools/Sailfish_SDK/OBS_Packaging => Services/Development/Open_Build_Service/Packaging_for_OBS}/README.md (100%) diff --git a/Tools/Sailfish_SDK/OBS_Packaging/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md similarity index 100% rename from Tools/Sailfish_SDK/OBS_Packaging/README.md rename to Services/Development/Open_Build_Service/Packaging_for_OBS/README.md From a7436e703ed3199d4d7f5d04a9f364dd7b9c7785 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:49:47 +0200 Subject: [PATCH 06/17] Adjust header information after move --- .../Open_Build_Service/Packaging_for_OBS/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index f1c3887c..2e3eaee0 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -1,7 +1,7 @@ --- title: Packaging Software on OBS -permalink: Tools/Sailfish_SDK/OBS_Packaging -parent: Sailfish SDK +permalink: Services/Development/Open_Build_Service/Packaging_for_OBS +parent: Open Build Service layout: default nav_order: 400 --- From db2986a116401fc522af6ecc76fae686dcb65ec8 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:53:23 +0200 Subject: [PATCH 07/17] Add link to the new page --- Services/Development/Open_Build_Service/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Services/Development/Open_Build_Service/README.md b/Services/Development/Open_Build_Service/README.md index d7f6d7bb..f00a3fb8 100644 --- a/Services/Development/Open_Build_Service/README.md +++ b/Services/Development/Open_Build_Service/README.md @@ -23,6 +23,8 @@ If the build fails, either due to a missing dependency specification in the .spe If the build succeeds, a set of automated tests will be run (if specified for the package), allowing a first-stage quality gate to be applied. If those automated tests succeed, the package will be accepted to the next stage of releasing. +See [Packaging Software on OBS] for more. + ## Promotion in OBS When a package is promoted, it becomes accessible to any device which has that repository added to their update configuration (modifiable via the `ssu` command). There are different promotion layers which correspond to different release types: From a96fceab9766a5eee86d0f921bd9dc3a4a43ec19 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:56:38 +0200 Subject: [PATCH 08/17] fixup! Adjust header information after move --- Services/Development/Open_Build_Service/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Services/Development/Open_Build_Service/README.md b/Services/Development/Open_Build_Service/README.md index f00a3fb8..69f5f7fe 100644 --- a/Services/Development/Open_Build_Service/README.md +++ b/Services/Development/Open_Build_Service/README.md @@ -23,7 +23,7 @@ If the build fails, either due to a missing dependency specification in the .spe If the build succeeds, a set of automated tests will be run (if specified for the package), allowing a first-stage quality gate to be applied. If those automated tests succeed, the package will be accepted to the next stage of releasing. -See [Packaging Software on OBS] for more. +See [Packaging Software on OBS](/Services/Development/Open_Build_Service/Packaging_for_OBS) for more. ## Promotion in OBS From 1e1d7128046d0645065da6c3fe15b6172e11efe8 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 11:57:01 +0200 Subject: [PATCH 09/17] Remove self-referencing link --- Services/Development/Open_Build_Service/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Services/Development/Open_Build_Service/README.md b/Services/Development/Open_Build_Service/README.md index 69f5f7fe..e1800aa5 100644 --- a/Services/Development/Open_Build_Service/README.md +++ b/Services/Development/Open_Build_Service/README.md @@ -17,7 +17,7 @@ Each package is added under a *project*. For example, there is a [ofono](https:/ ## Building in OBS -After the maintainer has tagged the repository, the CI system will be informed (via webhook) of the change. This will trigger a package build in [OBS](/Services/Development/Open_Build_Service). OBS will attempt to build the package, with a build environment constructed specifically for that package after examining the build requirements which are listed in its RPM .spec file. +After the maintainer has tagged the repository, the CI system will be informed (via webhook) of the change. This will trigger a package build in OBS. OBS will attempt to build the package, with a build environment constructed specifically for that package after examining the build requirements which are listed in its RPM .spec file. If the build fails, either due to a missing dependency specification in the .spec file, or due to a code error, the package will not be tested, and the developer is expected to respond to the failure notification and fix the issue. From 1ae21f43ac1567a8864a2cc4040156399a5c9e7a Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Mon, 30 Sep 2024 23:51:12 +0200 Subject: [PATCH 10/17] Add section about advanced trickery --- .../Packaging_for_OBS/README.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index 2e3eaee0..4160ffda 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -376,3 +376,86 @@ Support x64, arm, arm64, build for both arm and arm64, but only publish arm64: ``` + +## Advanced Trickery + +### OBS Branches and `tar_git` + +One of the drawbacks of using a `_service` file and "Packaging Repository" +setups is that the OBS feature of [branching](https://openbuildservice.org/help/manuals/obs-user-guide/art-obs-bg#sec-obsbg-uc-branchprj) +becomes less useful, because your branched package will only contain the +`_service` file, but not any sources to change. + +You can of course fork the git repo specified in the `_service` file, and make +changes as usual. But you might not want to do that. + +Luckily, there is a workaround: + +As branches are links, and the link concept of OBS supports patching the source +files before the build process starts through the `apply` tag of the `_link` +file, we can do some changes locally, create a patch, and add that patch to the +`_link` file. + +This is prettty hard to do on the Web Interface alone, so here we assume usage of `osc`. + +In this example, we assume what you want to change is the .spec file, but the +same process applies to any file in the packaging repo you can use a patch to +change. + +First, create a branch on OBS as usual, and check it out + +``` +osc branch path:to:source:project sourcepackage +osc co home:username:branches:path:to:source:project sourcepackage +``` +*(Alternatively, you can just use linking instead of branching)* + +Your branched package will contain just the `_service` file, which is not very +useful if you actually want to change something in the build process (the.spec +file). + +Lets change to link view in the local package: + +``` +osc up --unexpand-link +``` + +The contents of the local checkout will change to a `_link` file. Edit it and configure the `apply` tag: + +``` + +``` + +Get a local copy of the tag_git-generated .spec file: + +``` +mkdir a +mkdir b +osc cat _service:tar_git:myapp.spec > a/_service:tar_git:myapp.spec +cp a/_service:tar_git:myapp.spec b/_service:tar_git:myapp.spec +``` + +Now, apply your changes to the file `b/_service:tar_git:myapp.spec`. + +When finished, do + +``` +diff -u a b > spec.patch +``` + +Now the files are in place, and the `_link` file has been edited, lets commit: + + +``` +osc add spec.patch +osc commit +``` +*(Note we add just the spec file, and no other files.* + +OBS will now: + + 1. check out the sources from the upstream repos as usual + 1. apply the path `spec.patch` to these sources + 1. Comtinue the building as usual. + + From fb2a7b9d6c84a1fdfa6dc329aefa34a84901b924 Mon Sep 17 00:00:00 2001 From: "Peter G. (nephros)" Date: Tue, 1 Oct 2024 00:12:54 +0200 Subject: [PATCH 11/17] fixup! Add section about advanced trickery --- .../Development/Open_Build_Service/Packaging_for_OBS/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index 4160ffda..bc498eb6 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -450,7 +450,7 @@ Now the files are in place, and the `_link` file has been edited, lets commit: osc add spec.patch osc commit ``` -*(Note we add just the spec file, and no other files.* +*(Note we add just the spec file, and no other files.)* OBS will now: From 1b2cc6246770a4bba73319fb6060ae1d28560bac Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 1 Oct 2024 10:33:57 +0200 Subject: [PATCH 12/17] Improve the advanced trickery --- .../Packaging_for_OBS/README.md | 59 ++++++++++--------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index bc498eb6..3ba706b1 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -402,60 +402,61 @@ In this example, we assume what you want to change is the .spec file, but the same process applies to any file in the packaging repo you can use a patch to change. -First, create a branch on OBS as usual, and check it out +**Overview:** -``` -osc branch path:to:source:project sourcepackage -osc co home:username:branches:path:to:source:project sourcepackage -``` -*(Alternatively, you can just use linking instead of branching)* + 1. Create a branch (or a link) of the package in question + 1. Check out the package sources in "unexpand mode" + 1. Get copies of the tar\_git-generated .spec file + 1. Set up a local structure we can later use with `diff` to create a patch + 1. Create a patch containing the changes to the tar\_git-generated .spec file + 1. Edit the `_link` file, using the `` tag to include our patch -Your branched package will contain just the `_service` file, which is not very -useful if you actually want to change something in the build process (the.spec -file). -Lets change to link view in the local package: +**Step-by-Step**: ``` +# Create a branch and check it out +osc branch path:to:source:project sourcepackage +# Alternatively, use linking instead of branching: +# osc branch path:to:source:project sourcepackage path:to:my:local:project sourcepackage +osc co home:username:branches:path:to:source:project sourcepackage +cd home:username:branches:path:to:source:project/sourcepackage +# Fetch the _link file: osc up --unexpand-link ``` -The contents of the local checkout will change to a `_link` file. Edit it and configure the `apply` tag: - +Edit the `_link` file to contain ``` ``` -Get a local copy of the tag_git-generated .spec file: +Perform whatever changes to the file we want to do, and create a patch: +*Note: the reason we use the a/b directories and don't just leave the spec file +in the package root is that `osc` will actually delete it on the next commit.* ``` +# list the contents of the package directory, just so we can confirm the exact name of the extracted .spec file +osc status +# Fetch the .spec file and put it in our local a/b workspace mkdir a -mkdir b osc cat _service:tar_git:myapp.spec > a/_service:tar_git:myapp.spec -cp a/_service:tar_git:myapp.spec b/_service:tar_git:myapp.spec -``` - -Now, apply your changes to the file `b/_service:tar_git:myapp.spec`. - -When finished, do - -``` +cp -r a b +$EDITOR b/_service:tar_git:myapp.spec diff -u a b > spec.patch ``` -Now the files are in place, and the `_link` file has been edited, lets commit: - - +Finally, add the patch file and commit: ``` osc add spec.patch -osc commit +osc commit spec.patch _link ``` -*(Note we add just the spec file, and no other files.)* + +*(Note we add just the `spec.patch` file, and no other files.)* OBS will now: - 1. check out the sources from the upstream repos as usual + 1. check out the sources and .spec file from the upstream repos as usual 1. apply the path `spec.patch` to these sources - 1. Comtinue the building as usual. + 1. Continue the building as usual. From 9563286455c610a692cec23ccd2c3d3f1c466dd7 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 1 Oct 2024 10:34:43 +0200 Subject: [PATCH 13/17] Rework the introduction --- .../Packaging_for_OBS/README.md | 73 ++++++++++--------- 1 file changed, 39 insertions(+), 34 deletions(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index 3ba706b1..7dd49130 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -6,21 +6,27 @@ layout: default nav_order: 400 --- -This page deals specifically with building packages using the [Open Build Service](/Services/Development/Open_Build_Service) instance. +This page deals specifically with building packages using the [Open Build +Service](/Services/Development/Open_Build_Service) instance, and tries to cover +all the tasks necessary and some pitfalls along the way. +While this may seem lengthy at first glance, the actual steps involved are not that many. -This requires the user to create a home project, and then create a package -under that project, with the appropriate `_service` file to specify how the -project should be built and packaged. Once the build has been triggered, OBS -will attempt to pull in the required dependencies and build the package. +The highlevel overview of the process looks like this: + + + 1. Get an account on OBS + 1. Create a project, and a package on OBS + 1. Upload the source files, or a special `_service` file to the OBS package + 1. Adjust the .spec file for some peculiarities involved with building on OBS You can interact with the OBS either on the web interface at [https://build.sailfishos.org](https://build.sailfishos.org), or use the command-line tool, [osc](https://en.opensuse.org/openSUSE:OSC) **A note about terminology** -*Some terms, like "repository", "source", "package", have different meanings -depending on context. For example "repo" can mean either a build environment -configuration on OBS, or it's corresponding published RPM repository. But it -can also refer to a git repository.* +*Some terms, like "repository", "source", "project", "package", have different +meanings depending on context. For example "repo" can mean either a build +environment configuration on OBS, or it's corresponding published RPM +repository. But it can also refer to a git repository.* ## Setting up the (Home) Project and creating a Package @@ -31,10 +37,24 @@ You can create various packages in that project and also create sub-projects. See the official OBS [Beginnerʼs Guide](https://openbuildservice.org/help/manuals/obs-user-guide/art-obs-bg) for an introduction to OBS in general. +In your project, click on "Repositories", ignore all the checkmarks offered, and select only "SailfishOS latest". +This should be enough to get a basic build environment set up. You can add more repositories and architectures to build against later. + Click "Create Package" in your project if using the Web Interface, or `osc mkpac mypackage` if using `osc` to get started. + ## Adding the sources +To get the source files into your OBS Project, either upload them using the Web Interface, or use the `osc` tool: + +``` +cd my:project:mypackage +cp /path/to/mypackage.tar.bz2 . +cp /path/to/mypackage.spec . +osc add * +osc commit +``` + There are about three common "packaging formats" used in Sailfish OS development, which are described under [Packaging Formats](https://docs.sailfishos.org/Tools/Sailfish_SDK/Building_packages/#packaging-formats): - Plain Tarball @@ -45,45 +65,35 @@ A packaging repository is a git repository which contains just the build instructions and some other files (like patches) to package software for Sailfish OS, with the actual source code living in a git submodule of this repository. -An "Application Repository" contains the source code itself, e.g. because you wrote it or cloned a third-party git repository. +An "Application Repository" contains the source code itself, e.g. because you +wrote it or cloned a third-party git repository. ### Plain Tarball sources Usually, nothing special needs to be done if you want to build software from a source tarball. +Just populate the OBS Package like below, OBS will pick up both and run the build. No `_service` file is necessary in this case. -You just populate the OBS package source like this: +However, you must place a .spec file alongside the source tarball, it cannot be contained within the tarball. ``` application.spec application-1.2.3.tar.gz ``` -OBS will pick up both and run the build. No `_service` file is necessary in this case. - -To get the source information into OBS, either upload them using the Web Interface, or use the `osc` tool: - -``` -cd my:project:mypackage -cp /path/to/mypackage.tar.bz2 . -cp /path/to/mypackage.spec . -osc add * -osc commit -``` - *Note: Using a plain tarball is an convenient and quick way to package software on OBS. Still, you are encouraged to move to a "Packaging Repo" approach for various reasons, including better revision control and history, easier forking -by others, and backup/restore considerations.* +by others, and considerations about backup/restore ### `tar_git` sources `tar_git` is a OBS Service which clones a repository from a public git hoster, creates a tarball from it, extracts the build information, and places all those -files into the OBS Package source location. +files into the OBS Package source location. After this it starts to build the package. -You may look at its [source code](https://github.com/MeeGoIntegration/obs-service-tar-git) detailed information. +To get the service configured on OBS, create a file called `_service` with the +following content, and then upload that file like you would a source file: -To get the service configured on OBS, create a file called `_service` with the following content: ``` @@ -97,13 +107,8 @@ To get the service configured on OBS, create a file called `_service` with the f ``` -and then either upload them using the Web Interface, or use the `osc` tool: -``` -cd my:project:mypackage -cp /path/to/_service . -osc add _service -osc commit -``` +You may want to look at its [source code](https://github.com/MeeGoIntegration/obs-service-tar-git) detailed information about `tar_git`. + #### Understanding version mangling performed by `tar_git` From c8f581ac9f744bf4e8c5b8cfdba3952000b5ca70 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 1 Oct 2024 10:35:21 +0200 Subject: [PATCH 14/17] Consistent use of .spec with a dot --- .../Packaging_for_OBS/README.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index 7dd49130..894b69aa 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -129,7 +129,7 @@ For some examples, see below. - Z is a counter starting at 1 and increasing each time OBS decides to automatically rebuild the package (usually because a dependency was rebuilt or newly published) These auto-generated revision and version parameters will replace the -`%version` and `%revision` macros in the spec file throughout the OBS build +`%version` and `%revision` macros in the .spec file throughout the OBS build process. So you cannot use literal version or revision contents in your build setup. If you need those, you should parse `%version` and `%revision`. @@ -146,7 +146,7 @@ Be aware though that the parser above is not perfect. Also, some characters are disallowed to appear in RPM version strings. So be conservative in the naming of your tags. -#### Understanding the source structure and tarballs generated by `tar_git` +#### Understanding cloning, the source structure, and tarballs generated by `tar_git` The tarball produced by the service has the following properties: @@ -259,7 +259,7 @@ checked out OBS package, or "Trigger Services" from the Web Interface. **ERROR: no packaging in this git clone** -Your project does not contain a spec file in the `rpm` directory. +Your project does not contain a .spec file in the `rpm` directory. **ERROR: couldn't clone foo** @@ -278,17 +278,17 @@ still fail with the same error. You will need to seek assistance from the OBS maintainers in that case. See also [this bug](https://github.com/MeeGoIntegration/obs-service-tar-git/issues/3). -**ERROR: Need single spec file in rpm** +**ERROR: Need single .spec file in rpm** Your project does contain a directory called `rpm`, but that directory contains more than one .spec file, so `tar_git` gets confused. -There are three possible solutions for that. +There are two possible solutions for that. 1. delete one of the .spec files in the repo ;) - 1. name the OBS package or the spec file so their names match exactly. `tar_git` will accept a spec file that has the same name as the project. + 1. name the OBS package or the .spec file so their names match exactly. `tar_git` will accept a .spec file that has the same name as the project. - Note that if you actually want to build all the spec files, you can either use OBS Links (`_link`), or `_multibuild` files to achieve that. - Either create links that correspond to the names of the other spec files or create a `_multibuild` file using the spec file names as `flavor`: + Note that if you actually want to build all the .spec files, you can either use OBS Links (`_link`), or a [Multibuild](https://openbuildservice.org/help/manuals/obs-user-guide/cha-obs-multibuild) setup to achieve that. + Either create linked Packages that have the same name as the other .spec files or create a `_multibuild` file using the .spec file names as `flavor`: ``` @@ -296,7 +296,8 @@ There are three possible solutions for that. bar ``` -**ERROR: couldn't determine version from spec file** + +**ERROR: couldn't determine version from .spec file** Something is fishy about the `Version:` line in the .spec, or it is missing completely From 56f7e5f5bb82834ec11fddb75921f827c0417366 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 1 Oct 2024 10:37:55 +0200 Subject: [PATCH 15/17] Fix spelling --- .../Open_Build_Service/Packaging_for_OBS/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index 894b69aa..59c526d0 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -11,7 +11,7 @@ Service](/Services/Development/Open_Build_Service) instance, and tries to cover all the tasks necessary and some pitfalls along the way. While this may seem lengthy at first glance, the actual steps involved are not that many. -The highlevel overview of the process looks like this: +The high-level overview of the process looks like this: 1. Get an account on OBS @@ -254,7 +254,7 @@ BuildRequires: pkgconfig(Qt5Xml) ## Common errors -To retry after fixong an error, run either `osc service rr` from the locally +To retry after fixing an error, run either `osc service rr` from the locally checked out OBS package, or "Trigger Services" from the Web Interface. **ERROR: no packaging in this git clone** @@ -402,7 +402,7 @@ files before the build process starts through the `apply` tag of the `_link` file, we can do some changes locally, create a patch, and add that patch to the `_link` file. -This is prettty hard to do on the Web Interface alone, so here we assume usage of `osc`. +This is pretty hard to do on the Web Interface alone, so here we assume usage of `osc`. In this example, we assume what you want to change is the .spec file, but the same process applies to any file in the packaging repo you can use a patch to From cf331d30e36f50902a44c90cf34ca3508cda0542 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 1 Oct 2024 10:53:14 +0200 Subject: [PATCH 16/17] Try highlighing syntax --- .../Packaging_for_OBS/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index 59c526d0..2de11a5f 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -47,7 +47,7 @@ Click "Create Package" in your project if using the Web Interface, or `osc mkpac To get the source files into your OBS Project, either upload them using the Web Interface, or use the `osc` tool: -``` +```sh cd my:project:mypackage cp /path/to/mypackage.tar.bz2 . cp /path/to/mypackage.spec . @@ -94,7 +94,7 @@ files into the OBS Package source location. After this it starts to build the pa To get the service configured on OBS, create a file called `_service` with the following content, and then upload that file like you would a source file: -``` +```xml https://github.com/orgname/reponame.git @@ -202,7 +202,7 @@ single source code file and a Makefile, without any directory structure.* The name of the tarball must be the first `Source:` line in the .spec file. You should name it -``` +```specfile Source: %{name}-%{version}.tar.bz2 ``` @@ -218,7 +218,7 @@ as the main source. So if the upstream submodule is called "upstream", the line should look like -``` +```specfile %prep %setup -q -n %{name}-%{version}/upstream ``` @@ -243,7 +243,7 @@ fine under the SDK. Typically this involves the Qt dependencies, so you will need to add lines like the following: -``` +```specfile BuildRequires: pkgconfig(Qt5Qml) BuildRequires: pkgconfig(Qt5Quick) BuildRequires: pkgconfig(Qt5Widgets) @@ -267,7 +267,7 @@ Check the `url` parameter in the `_service` file. Also, check the settings on your git host. The repository may be set to private. And be sure to use a clone URL, not a web view of the repo (like git-web). -``` +```xml https://github.com/sailfishos-chum/qt6.git gcc ``` @@ -290,7 +290,7 @@ There are two possible solutions for that. Note that if you actually want to build all the .spec files, you can either use OBS Links (`_link`), or a [Multibuild](https://openbuildservice.org/help/manuals/obs-user-guide/cha-obs-multibuild) setup to achieve that. Either create linked Packages that have the same name as the other .spec files or create a `_multibuild` file using the .spec file names as `flavor`: -``` +```xml foo bar @@ -353,7 +353,7 @@ With `osc`, the commands are: `osc meta -e prj`, and `osc meta -e pkg` Support x64, arm, arm64, build for both arm and arm64, but only publish arm64: -``` +```xml Foo The Foo suite of software @@ -420,7 +420,7 @@ change. **Step-by-Step**: -``` +```sh # Create a branch and check it out osc branch path:to:source:project sourcepackage # Alternatively, use linking instead of branching: From e3ae1acb5ec6ff885a37adb886465ba58f142adf Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 1 Oct 2024 10:53:59 +0200 Subject: [PATCH 17/17] Reword, reformat --- .../Packaging_for_OBS/README.md | 35 +++++++++---------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md index 2de11a5f..45c480c6 100644 --- a/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md +++ b/Services/Development/Open_Build_Service/Packaging_for_OBS/README.md @@ -169,11 +169,11 @@ So the root may end up looking like this: ``` **A note about "dumb" packages:** -*You notice there is a "dumb" parameter in the service configuration. Setting -this to true switches the behaviour of the service to assume a very flat source -structure, and not generate a tarball. -You may use this if your sources are very simple, for example contain only a -single source code file and a Makefile, without any directory structure.* +*You'll notice there is a "dumb" parameter in the service configuration. Setting +this to true switches the behaviour of the service to assume a flat source +structure without any directories and not generate a tarball. +You may want to use this if your sources are very simple, for example contain only a +single source file and a Makefile.* **Some Examples** @@ -197,7 +197,7 @@ single source code file and a Makefile, without any directory structure.* `_service:tar_git:foo-2.2+git3.tar.bz2` -#### Adjust the %setup macro parameters and other paths +#### Adjust the spec file: %setup macro and other paths The name of the tarball must be the first `Source:` line in the .spec file. @@ -224,16 +224,14 @@ So if the upstream submodule is called "upstream", the line should look like ``` You can choose a literal string as the name, but you must use the `%{version}` macro. -Similarly, if you change working directories in the build process, be aware of where the actual source code is located relative to `%{_builddir}`: - -`%{_builddir}/%{name}-%{version}/upstream` +Similarly, if you change working directories in the build process, be aware of where the actual source code is located relative to `%{_builddir}`: `%{_builddir}/%{name}-%{version}/upstream` On the other hand, the contents of the `rpm` sub-directory will be in the package root, not under `rpm` or `%_topdir/SOURCES` during the build. Usually, this does not affect you though, as OBS sets the internal source path accordingly, so things like `%SOURCE2` will work as expected. -#### Adjust the build requirements (BuildRequires). +#### Adjust the spec file: build requirements (BuildRequires). The building service runner setup used on OBS is more bare-bones than the one used in the Sailfish SDK, also with regard to the pre-installed packages. If @@ -250,7 +248,7 @@ BuildRequires: pkgconfig(Qt5Widgets) BuildRequires: pkgconfig(Qt5Xml) ``` -==== +--- ## Common errors @@ -405,16 +403,15 @@ file, we can do some changes locally, create a patch, and add that patch to the This is pretty hard to do on the Web Interface alone, so here we assume usage of `osc`. In this example, we assume what you want to change is the .spec file, but the -same process applies to any file in the packaging repo you can use a patch to -change. +same process applies to any file in the packaging repo you can change using a patch. **Overview:** 1. Create a branch (or a link) of the package in question 1. Check out the package sources in "unexpand mode" - 1. Get copies of the tar\_git-generated .spec file + 1. Get copies of the extracted .spec file 1. Set up a local structure we can later use with `diff` to create a patch - 1. Create a patch containing the changes to the tar\_git-generated .spec file + 1. Create a patch containing the changes to the .spec file 1. Edit the `_link` file, using the `` tag to include our patch @@ -432,13 +429,14 @@ osc up --unexpand-link ``` Edit the `_link` file to contain -``` +```xml ``` Perform whatever changes to the file we want to do, and create a patch: + *Note: the reason we use the a/b directories and don't just leave the spec file -in the package root is that `osc` will actually delete it on the next commit.* +in the package root is that `osc` would actually delete that on the next commit.* ``` # list the contents of the package directory, just so we can confirm the exact name of the extracted .spec file @@ -447,6 +445,7 @@ osc status mkdir a osc cat _service:tar_git:myapp.spec > a/_service:tar_git:myapp.spec cp -r a b +# Make some changes: $EDITOR b/_service:tar_git:myapp.spec diff -u a b > spec.patch ``` @@ -463,6 +462,6 @@ OBS will now: 1. check out the sources and .spec file from the upstream repos as usual 1. apply the path `spec.patch` to these sources - 1. Continue the building as usual. + 1. continue the building as usual