new upstream release of fd-find

[debcargo-conf.git] / README.rst

diff --git a/README.rst b/README.rst
index ca27ec956214975fb1b3378091c4997749c2b9d9..c94c8ed8ba779451741ad8f6c8366226aa3e4e29 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -3,8 +3,11 @@ Instructions
 
 To get set up, run::
 
-  apt update && apt build-dep cargo && apt install cargo dh-cargo
-  cargo install debcargo # eventually will be replaced by "apt install debcargo"
+  apt update && apt install cargo debcargo
+
+As your regular user, update the crates.io index:
+
+  cargo search
 
 Then for each new package:
 
@@ -57,17 +60,6 @@ on having to package all the dependencies of the newest version, you can::
   REALVER=<old-version> ./release.sh <rust-crate-name>
 
 
-DD instructions
-===============
-
-To set up a suitable build environment for ``./build.sh``::
-
-  $ sudo apt-get install devscripts reprepro debootstrap sbuild
-  $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian \
-      --chroot-prefix debcargo-unstable unstable \
-      /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
-
-
 General packaging tips
 ======================
 
@@ -132,7 +124,64 @@ For now, testsuites aren't executed for library.
 However, for binary, it is strongly recommended to run the testsuites.
 See ripgrep as example.
 
-TODO
-====
+Updating the dependencies
+-------------------------
+
+In some cases, libraries/programs are forcing an old version of a library as
+dependencies. In order to limit the number of duplicated libraries in the
+archive, please try to evaluate if a newer version of the dependencies could be
+used.
+
+To achieve that, after ./update.sh, try::
+
+  $ cd build/<package>/
+  $ rm -rf .pc # sometimes this is necessary due to minor debcargo bug
+  $ quilt push -a
+  $ quilt new relax-dep.diff
+  $ quilt edit Cargo.toml
+  $ quilt refresh
+  $ cargo build # check that it works. if it does, then
+  $ cp -R patches ../../src/<package>/debian
+
+Suppose you want to change the dependency from 0.3 to 0.5. If the crate builds
+with no further source changes, then we would change the required version in
+``Cargo.toml`` from ``0.3`` to ``>= 0.3, < 0.6`` or something like that. Then
+the convention is to put all these changes into a single patch called
+``relax-dep-versions.patch``.
+
+OTOH, if the cargo build fails, and you can fix it up by editing the source
+code in a minor way to use the new crate API, then: for each crate that needs
+to be updated, you should instead name the patch ``update-dep-<crate>.patch``
+and add both the ``Cargo.toml`` and the source code changes to it. Use
+``quilt rename`` if that helps you.
+
+
+DD instructions
+===============
+
+To set up a suitable build environment for ``./build.sh``::
+
+  $ sudo apt-get install devscripts reprepro debootstrap sbuild
+  $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
+      --chroot-prefix debcargo-unstable unstable \
+      /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
 
-Maybe use ``--copyright-guess-harder``.
+Normally, ``./build.sh`` will fail early if not all the build dependencies are
+available in your local apt cache. If you are packaging a large dependency tree
+however, to avoid many round-trips through NEW it is possible to bypass this
+check and build all the packages together. Suppose package B depends on package
+A, then you can run something like::
+
+  $ export IGNORE_MISSING_BUILD_DEPS=1
+  $ ./release.sh A
+  $ ( cd build && ./build.sh A )
+  # push pending and checkout master
+  $ ./release.sh B
+  $ ( cd build && ./build.sh B librust-A*.deb )
+
+The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
+sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
+been built by the previous step.
+
+After everything is built successfully, you can ``dput`` all of them and then
+push all the ``pending-*`` branches as normal.