From d1b39e015fe8a386e640b5c228c61c0597ee0f17 Mon Sep 17 00:00:00 2001 From: clime Date: Mar 08 2018 22:08:04 +0000 Subject: update README.md --- diff --git a/README.md b/README.md index ce2f63c..d5a2cb5 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,110 @@ -This application is an RPM packaging utility based on python-rpkg library. It works with both [DistGit](https://github.com/release-engineering/dist-git) -and Git repositories and it handles two types of directory content: _packed_ content and _unpacked_ content. +`rpkg` is an RPM packaging utility based on python-rpkg library. -- Packed (unexpanded) content is that composed of tarballs, patches, and a .spec file. -- Unpacked (expanded) content is that composed of plain source files and a .spec file. +It works with both [DistGit](https://github.com/release-engineering/dist-git) +and standard Git repositories. -Currently `rpkg` offer two ways of achieving this: +It handles two types of directory content: _packed_ and _unpacked_. + +- *Packed (unexpanded) content is that composed of tarballs, patches, and a .spec file* +- *Unpacked (expanded) content is that composed of plain source files and a .spec file* + +There are currently two ways of handling those two different content types: - spec templates - autopacking (deprecated) -Spec templates: - Name: {{{ git_name }}} - Version: {{{ git_version }}} - Release: 1%{?dist} - Summary: This is a test package. +Spec templates +-------------- - License: GPLv2+ - URL: https://someurl.org +Apart from being useful as a means to handle unpacked (as well as packed) content, +they also make it possible to generate potentially large parts of your spec file +automatically from a Git repository where your spec file is located. - Source: {{{ git_pack }}} +An example spec template might look like this: - %description - This is a test package. +``` +Name: {{{ git_name }}} +Version: {{{ git_version }}} +Release: 1%{?dist} +Summary: This is a test package. - %prep - {{{ git_setup_macro }}} +License: GPLv2+ +URL: https://someurl.org - {{{ git_changelog }}} +Source: {{{ git_pack }}} -TODO: write up more! +%description +This is a test package. -Autopacking (deprecated): +%prep +{{{ git_setup_macro }}} -If you have auto_pack option enabled in your config, then for packed content, if you ask `rpkg` -to make srpm (`rpkg srpm`), it will download any external files from the appropriate storage -(e.g. lookaside cache for DistGit) and then it will invoke `rpmbuild -bs` with `_sourcedir`, -`_specdir`, `_builddir`, `_srcrpmdir`,`_rpmdir` macros all set to the working directory. +%changelog +{{{ git_changelog }}} +``` -For unpacked content, if you ask `rpkg` to do the same thing, it will download external sources (if any) -and then it will also generate a tarball from the whole content of the working directory named according -to `Source0` definition present in the associated .spec file. This tarball and the .spec are then passed -to the same rpmbuild command as above for the packed content. +Having a spec template like this in your project (instead of just a plain spec file) +allows your built source packages to automatically follow git history of your project. -Apart from generating srpms from the application sources, you can also run other useful packaging commands -like `rpkg lint` to check the .spec file and the overall package conformance to RPM standard, `rpkg local` -to locally build the package into an rpm, or `rpkg copr-build` to build an srpm and send it for build to -[COPR](https://copr.fedorainfracloud.org). +Read more [here](https://docs.pagure.org/rpkg-util/tutorials.html#spec-templates-from-scratch). + + +Auto-packing (deprecated) +------------------------- + +Auto-packing works only if `auto_pack` configuration option is set to `True` and only if the content +you are working with is not packed (see `rpkg is-packed`). + +When invoking `rpkg srpm` on an unpacked content, `rpkg` will download external sources (if any) +and then it will generate a tarball from the whole content of the working directory named according +to `Source0` definition present in the associated .spec file. This tarball and the .spec file are +then passed to rpmbuild to generate the resulting srpm. + + +More examples +------------- + +Run %prep phase of an rpm build: -Examples: -``` - $ cd unpacked-copr-build-example - $ ls . - doc LICENSE README.md rpkg rpkg.bash rpkg-client.spec rpkg.conf rpkglib run_tests.sh setup.py tests - $ rpkg copr-build user/project - Wrote: copr-build-example/rpkg-client-0.8.tar.gz - Wrote: copr-build-example/rpkg-client-0.8-1.fc25.src.rpm - Uploading package rpkg-client-0.8-1.fc25.src.rpm - 100% |################################| 49kB 263kB/s eta 0:00:00 - Build was added to example: - https://copr.fedorainfracloud.org/coprs/build/625402/ - Created builds: 625402 - ... -``` ``` - $ cd prep-example - $ ls . - doc LICENSE README.md rpkg rpkg.bash rpkg-client.spec rpkg.conf rpkglib run_tests.sh setup.py tests - $ rpkg make-source - Wrote: rpkg-client/rpkg-client-0.8.tar.gz $ rpkg prep - Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.bd5cCF + git_pack: Source file already exists. No action taken. + Wrote: /tmp/rpkg/rpkg-client.spec + Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.4iFciz + umask 022 - ... - $ rpkg clean + + cd /tmp/rpkg/ + + cd /tmp/rpkg + + rm -rf rpkg-client-1.0.git.122.e59a5b11 + + /usr/bin/gzip -dc /tmp/rpkg/rpkg-client-1.0.git.122.e59a5b11.tar.gz + + /usr/bin/tar -xof - + + STATUS=0 + + '[' 0 -ne 0 ']' + + cd rpkg-client-1.0.git.122.e59a5b11 + + /usr/bin/chmod -Rf a+rX,u+w,g-w,o-w . + + exit 0 ``` -You can find more information and more examples in rpkg man pages (`man rpkg`). +For the following command, you need to have a project in COPR created. +See quick tutorial [here](https://docs.pagure.org/copr.copr/user_documentation.html#quick-start) on how to do it. + +``` + $ rpkg copr-build @releng/rpkg-util + git_pack: Wrote: /tmp/rpkg/rpkg-util-1.0.git.122.e59a5b11.tar.gz + Wrote: /tmp/rpkg/rpkg-util.spec + Wrote: /tmp/rpkg/rpkg-util-1.0.git.122.e59a5b11-1.fc27.src.rpm + Uploading package /tmp/rpkg/rpkg-util-1.0.git.122.e59a5b11-1.fc27.src.rpm + 100% |################################| 57kB 339kB/s eta 0:00:00 + Build was added to rpkg-util: + https://copr.fedorainfracloud.org/coprs/build/724892/ + Created builds: 724892 + Watching build(s): (this may be safely interrupted) + 15:50:12 Build 724892: importing ... +``` + +Other useful commands that you can use: + +- `rpkg lint` to check the .spec file and the overall package conformance to RPM standard +- `rpkg local` to locally build the package into an rpm +- `rpkg upload` to upload a new source to DistGit lookaside cache +- `rpkg ...` (see `rpkg --help` or `man rpkg`)