Become a maintainer. Part three

Published on January 31, 2009

Become a maintainer. Part three

    And there was the third day, and the habruble user-ubuntoid thought: how can I pack my favorite package so that it is beautiful and correct and that the pride from its kosher bursts like that. That is what we will do today.
    (Parts 1 , 2 and 4 )

    At the initiative of darkk, we will collect the redsocks package , which is translated into Russian as “darkk’s Red Socks."
    The first thing is to follow the link and download the archive with the source. I don’t know about you, but I have it called "darkk-redsocks-77a490422b701875a9fda2bd7d58e62cb7481f64.tar.gz". You understand, an archive with that name is not good. Therefore, we first unpack it and erase it:
    $ tar xvf darkk-redsocks-77a490422b701875a9fda2bd7d58e62cb7481f64.tar.gz
    $ rm darkk-redsocks-77a490422b701875a9fda2bd7d58e62cb7481f64.tar.gz

    Now we have a directory called "darkk-redsocks-77a490422b701875a9fda2bd7d58e62cb7481f64." It’s also no good. Fortunately, for extreme cases, for example, those where the program does not have any normal versions at all, Debian allows you to change the numbering. This is what we will do now:
    $ mv darkk-redsocks-77a490422b701875a9fda2bd7d58e62cb7481f64 darkk-redsocks-2009013101
    $ tar czf darkk-redsocks_2009013101.orig.tar.gz darkk-redsocks-2009013101

    The first action we rename the directory: now the version will be numbered by date plus the version number for the current date - this time the version will be 01. The second is to create a “kosher” source archive. Note, by the way, that the rules catalog should be named as “name-version”, and the archive as “name_version.orig.tar.gz”. In the first case, the version must be preceded by a hyphen, in the second - underscore.
    Now, oddly enough, if you are as familiar with the program as I am (that is, you see it for the first time in your life), then we install the libevent-dev package, which is indicated in the program dependencies, and without any frills we try to build our program: Personally, this procedure fell with an error:
    $ sudo apt-get install libevent-dev
    $ cd darkk-redsocks-2009013101
    $ make

    cc -std = gnu99 -Wall -g -O0 -c base.c -o base.o
    In file included from /usr/include/linux/netfilter_ipv4.h:8,
    from base.c: 29:
    / usr / include / linux / netfilter.h: 44: error: field 'in' has incomplete type
    /usr/include/linux/netfilter.h:45: error: field 'in6' has incomplete type
    make: *** [base.o] Error one

    And here one of the first commandments of the accompanying package comes into effect: either you very closely come into contact with the author of the upstream, or you become a major specialist in Internet search. This time, out of pride, I chose the second option and, through a thorough search, found that the bug was old. It has been showing up since six months and for some reason they are in no hurry to fix it. But you can make a local fix in the package and we will do it now (small remark: again, I don’t issue this as a separate patch, but correct it directly in the code, because such serious errors a cultural person must send to the author of the upstream and kick him while the patch it won’t be included in the upstream. If it doesn’t, it’s necessary for such authors of programs. Now, meanwhile, in the base.c file, before the line
    # include <linux/netfilter_ipv4.h>
    insert
    # include <netinet/in.h>

    Putting it again. Error again:
    cc parser.o main.o redsocks.o log.o http-connect.o socks4.o socks5.o http-relay.o base.o -levent -o redsocks
    main.o: In function `terminate ':
    / home / user / build / darkk-redsocks-2009013101 / main.c: 44: undefined reference to `event_loopbreak '

    We climb into the search again, we find nothing (at least I), but we understand by a monstrous telepathic effort that the event_loopbreak method that we have in the repository still does not know how. Okay, we say, what should we do? The new version in debian is only in the experimental repository. Personally, I did not dare to connect it. Therefore, we perform the following actions:
    $ cd ..
    $ sudo apt-get --purge remove libevent1 libevent-dev
    $ dget http://ftp.de.debian.org/debian/pool/main/libe/libevent/libevent_1.4.8~stable-1.dsc
    $ cd libevent-1.4.8~stable/
    $ debuild
    $ cd ..
    $ sudo dpkg -i ./libevent*.deb

    I explain. Since we don’t want to connect a repository in which the sea is terribly unstable software, we delete the existing libevent and collect the source package for the new version, which we downloaded using the dget command. Now that we have successfully installed the assembled package, we will try to assemble our red socks again:
    $ cd darkk-redsocks-2009013101/
    $ make

    This time everything was going well for me. Wonderful. Now we look around our catalog, try to understand what files should be collected in the final binary package that the user will install on his computer. Personally, I highlighted this set:
    doc / * -
    README documentation - the same
    redsocks.conf.example - example file
    redsocks - the executable itself

    Great, now let's try out a few options.

    Let's collect a govnopaket from ready-made binaries

    Yes, in other words, it's hard to call it, so I have to call it that.
    Attention, this assembly option is provided for information only and those who use it must be executed seven times in accordance with the laws of the country of Oz!
    So, we create inside our directory with the assembled program, another directory "darkk-redsocks-2009013101". We copy the files into it so that the following hierarchy is obtained:
    darkk-redsocks-2009013101/
    |-usr/
    .|-bin/
    .||-redsocks
    .|-share/
    ..|-doc/
    ...|-redsocks/
    ....|-COPYING
    ....|-README
    ....|-rfc1929-socks5-auth.txt
    ....|-rfc2817-http-connect.txt
    ....|-socks4a.protocol.txt
    ....|-rfc1928-socks5.txt
    ....|-rfc1961-socks5-gssapi.txt
    ....|-rfc3089-socks-ipv6.txt
    ....|-socks4.protocol.txt
    ....|-examples/
    .....|-redsocks.conf.example

    We create the darkk-redsocks-2009013101 / DEBIAN directory and put the control file in it with the following contents:
    Package: darkk-redsocks
    Version: 2009013101
    Architecture: amd64
    Maintainer: Ivan Ivanov <ivan@ivanov.iv>
    Description: transparent redirector of any TCP connection to proxy
     Mega-package which redirects any TCP connections to somewhat
     damn proxy.

    Since we still have to work with control files, I’ll give a little explanation right away. This file stores the entire description of the package - for which architecture it is built, who is accompanying it, etc. In principle, everything is clear there, only the Description item is of interest. It is arranged in a cunning way: in the first line, immediately after the word “Description:” a short description is written. Record it according to the rules so that it can be substituted in the line " Packagename is a description"That is, it is written with a small letter, without the subject and the word" is "(with a possible article), do not contain any punctuation marks at the end. Moreover, the name of the package should not be mentioned in the short description, and it should fit in one sentence and be no longer than 60 characters. Starting with the next line is a complete description of the package. Each line in the description should again be no longer than 80 characters (this, by the way, is a general requirement, including all kinds of scripts) and starts with a space. you want to insert an empty string in the description ku - put a space and a dot on it. Well, according to the good Debian tradition, the file should end with an empty line.
    Okay, the control file is finished. After we saved it, we collect our package with the command
    $ dpkg -b darkk-redsocks-2009013101

    In this case, darkk-redsocks-2009013101 is the name of our directory into which we pushed the files for the package, and in combination, it will also become the name of the received deb package. Enjoyed the sight? Now urgently typing
    $ rm -rf darkk-redsocks-2009013101 darkk-redsocks-2009013101.deb
    until I was completely sick of this build method. And move on to the next method.

    Putting together a package like cultural people

    And now, we are again in a situation where we have collected binaries and nothing more. Let's fix this situation. We type:
    $ make distclean

    We happily cleaned the catalog from both the binary and object files - from everything that was generated during the assembly. Now we type
    $ dh_make
    and we inform you of our passionate desire to create a package that generates a single binary, that is, a single binary. The dh_make utility refers to a set of debhelper utilities that terribly make life easier for package maintainers. She generated a debian directory for us, which contains the files used to build the package. Let's now go into this directory and delete everything except the following files:
    changelog
    compat
    control
    copyright
    docs
    rules

    In a good way, the watch file wouldn’t hurt us, but since we don’t have any normal, uploaded releases that you can follow, but only a git repository, we won’t need it. Now open the control file, delete everything from it and write a new, beautiful content:
    Source: darkk-redsocks
    Section: net
    Priority: optional
    Homepage: http://darkk.net.ru/redsocks
    Maintainer: Vsevolod Velichko <torkvemada@nigma.ru>
    Build-Depends: debhelper(>=7), libevent-dev(>=1.4.2)
    Standards-Version: 3.8.0
    Vcs-Git: git://github.com/darkk/redsocks.git
    Vcs-Browser: http://github.com/darkk/redsocks/tree/master

    Package: darkk-redsocks
    Architecture: any
    Depends: ${shlibs:Depends}, ${misc:Depends}
    Description: transparent redirector of any TCP connection to proxy
     Mega-package which redirects any TCP connections to somewhat
     damn proxy.

    Here, in principle, everything is clear, except for a couple of points. First comes the description of the source package, then, through an empty string, the binary package. “Architecture: any” means in this case that you can substitute any architecture into the compiled binary package — which one we build under will be substituted. If we were to build, for example, a dev package that is the same for all architectures, we would write there: “all”. Sometimes it is necessary that one src package collects several binary packages, for example, this is how qutIM I mentioned repeatedly is assembled - its source code provides not only the program itself, which is compiled into the qutim package, but also header files for potential plugins - we must put them into the qutim-dev package. In such cases, we write in the control file descriptions of several collected binary packages in a row, separating them with blank lines. Now the Build-Depends section. Firstly, it does not need to specify a compiler, make, etc. If you still don’t have a miracle, then install the build-essential package, and if it is already installed, open the file / usr / share / doc / build-essential / list, which contains a list of packages that you should never specify in build dependencies. Next up is the debhelper package. This is a package that provides us with many joys to build, it depends on its version how cool buns we can use. I recommend leaving the seventh version, because you can personally enjoy its buns when we write a script for assembly. Well, and libevent-dev, the package we were so tormented with once. Mandatory - indicating the version. If you still don’t have a miracle, then install the build-essential package, and if it is already installed, open the file / usr / share / doc / build-essential / list, which contains a list of packages that you should never specify in build dependencies. Next up is the debhelper package. This is a package that provides us with many joys to build, it depends on its version how cool buns we can use. I recommend leaving the seventh version, because you can personally enjoy its buns when we write a script for assembly. Well, and libevent-dev, the package we were so tormented with once. Mandatory - indicating the version. If you still don’t have a miracle, then install the build-essential package, and if it is already installed, open the file / usr / share / doc / build-essential / list, which contains a list of packages that you should never specify in build dependencies. Next up is the debhelper package. This is a package that provides us with many joys to build, it depends on its version how cool buns we can use. I recommend leaving the seventh version, because you can personally enjoy its buns when we write a script for assembly. Well, and libevent-dev, the package we were so tormented with once. Mandatory - indicating the version. which never need to be specified in dependencies for assembly. Next up is the debhelper package. This is a package that provides us with many joys to build, it depends on its version how cool buns we can use. I recommend leaving the seventh version, because you can personally enjoy its buns when we write a script for assembly. Well, and libevent-dev, the package we were so tormented with once. Mandatory - indicating the version. which never need to be specified in dependencies for assembly. Next up is the debhelper package. This is a package that provides us with many joys to build, it depends on its version how cool buns we can use. I recommend leaving the seventh version, because you can personally enjoy its buns when we write a script for assembly. Well, and libevent-dev, the package we were so tormented with once. Mandatory - indicating the version.
    We are going further. Open the compat file, check the number there - it should be the same as the debhelper version in the control file, that is 7. Why is it needed - to be honest, I don’t know myself, but to find out laziness. But you need :)
    Open the changelog file and bring it to the following form:
    darkk-redsocks (2009013101-1) experimental; urgency=low

      * Initial release (Closes: #123456)

     -- Vsevolod Velichko <torkvemada@nigma.ru>  Sat, 31 Jan 2009 04:07:47 +0300

    Note, we changed the release to experimental (for ubuntu, I suspect you need to install something like jaunty there), because we can only get the required version of the libevent-dev package there (actually, we downloaded it from there). The phrase “Closes: # 123456” is needed so that the debian or ubuntu bug tracking system when adding a package to the repository automatically closes the bug with the corresponding number. In the case of initial packaging, as with us, this is the number of the “bug” for planning the creation of the package — ITP (intend to package). Since we did not have such a bug, we will put an arbitrary number there until those times when we are going to include the package in the official repository. In the future, we will update changelog using the “dch” utility mentioned in the previous article by executing the “dch -i” command.
    Now go to the copyright file. It is already filled with a standard template, we just have to fill in the details. We bring it to this form:
    This package was debianized by Vsevolod Velichko <torkvemada@nigma.ru> on
    Sat, 31 Jan 2009 04:07:47 +0300.

    It was downloaded from http://darkk.net.ru/redsocks/

    Upstream Author:

        Leonid Evdokimov <leon@darkk.net.ru>

    Copyright:

        Copyright © 2009 Leonid Evdokimov

    License:

        This program is free software: you can redistribute it and / or modify
        it under the terms of the GNU General Public License as published by
        the Free Software Foundation, either version 3 of the License, or
        (at your option) any later version.

        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
        GNU General Public License for more details.

        You should have received a copy of the GNU General Public License
        along with this program. If not, see < http://www.gnu.org/licenses/ >.

    The Debian packaging is copyright 2009, Vsevolod Velichko <torkvemada@nigma.ru> and
    is licensed under the GPL, see `/ usr / share / common-licenses / GPL '.

    But then we begin editing files that, when creating a package, the magic debhelper package will process for us. The first thing is the docs file. It stores a list of files that will need to be installed in the documentation directory. In the general case, when our src package creates only one binary package during assembly, this file can be left under the name docs. But we, so as not to mess around in the possible future, immediately rename it by the name of the binary package:
    $ mv docs darkk-redsocks.docs

    Now open it and add all our documentation there:
    README
    doc / *

    The next item in the program is an example file. For him, we create a darkk-redsocks.examples file and write into it:
    redsocks.conf.example

    Since our Makefile does not know how to install a package, we also create a darkk-redsocks.install file. We write the following entry into it:
    redsocks usr / bin /
    Note that no slash is placed before usr.
    Files described? Wonderful, we just have to edit the last file. Open the rules file in the editor and start mercilessly uprooting it. Well, we don’t need the configure section, we don’t know how to do this - we delete it and all references to it. The remaining file is reduced to such an elegant look:
    #! / usr / bin / make -f
    # - * - makefile - * -

    # Uncomment this to turn on verbose mode.
    #export DH_VERBOSE = 1

    build: build-stamp
    build-stamp:
            dh build
            touch $ @

    clean:
            dh clean

    install: build
            dh install
            touch $ @

    binary-indep: install
            dh binary-indep

    binary-arch: install
            dh binary-arch

    binary : binary-indep binary-arch
    .PHONY: build clean binary-indep binary-arch binary install

    Please note: in the source file, all the calls looked like “dh_something”, for example, “dh_install”. These are the atomic reactions of a debhelper, about which you can read in the corresponding mans. We use commands like “dh install” when the call goes to the dh utility (also see the corresponding man page). This utility calls each script in turn from a specific group to which the passed parameter points. Thus, while we have a fairly simple package, most of these calls will be idle during assembly, but then, for example, if we add a mana page to the package, it will be enough to create the darkk-redsocks.manpages file, specify this page there, and at the next build, dh itself will put it where necessary, and even the script registering this page in mandb will add.
    So, we are done editing files. We exit from the debian directory to the parent directory and with a feeling of deep satisfaction we type:
    $ debuild --lintian-opts -i

    At the request of the password, we sign our resulting src-package, and then carefully look. The directory above we now have a set of files:
    darkk-redsocks_2009013101-1_amd64.build - this is the log in which the entire assembly progress of the
    darkk-redsocks_2009013101-1_amd64.changes package is recorded - this is an auxiliary file for the
    darkk-redsocks_2009013101-1_amd64.deb src package - the actual package itself for our
    darkk architecture redsocks_2009013101-1.diff.gz - a packaged diff file that stores all our changes, compared to the original sources. As a rule, this is all the contents of the debian directory, and in our case, remember the corrected base.c file?
    darkk-redsocks_2009013101-1.dsc - this is the main description file for the src package
    darkk-redsocks_2009013101.orig.tar.gz - well, this is the archive with source codes we created at the very beginning

    Someone might think that everything, this work is completed. If you're really lucky, then yes. In practice, this is where the simple and general part ends and individual disassembly begins with each with his own package. Well, we squandered our terminal back to the package assembly process. To whom he has already completely escaped - you can open the freshly assembled darkk-redsocks_2009013101-1_amd64.build file (you, of course, will have its own architecture instead of amd64), and look what the severe lintian censor tells us:
    Now running lintian ...
    W: darkk-redsocks: binary-without-manpage usr / bin / redsocks
    N:
    N: Each binary in / usr / bin, / usr / sbin, / bin, / sbin or / usr / games should
    N: have a manual page
    N:
    N: Note that though the man program has the capability to check for several
    N: program names in the NAMES section, each of these programs should have
    N: its own manual page (a symbolic link to the appropriate manual page is
    N: sufficient) because other manual page viewers such as xman or tkman
    N: don't support this.
    N:
    N: If the name of the man page differs from the binary by case, man may be
    N: able to find it anyway; however, it is still best practice to make the
    N: case of the man page match the case of the binary.
    N:
    N: If the man pages are provided by another package on which this package
    N: depends, lintian may not be able to determine that man pages are
    N: available. In this case, after confirming that all binaries do have man
    N: pages after this package and its dependencies are installed, please add
    N: a lintian override.
    N:
    N: Refer to Debian Policy Manual section 12.1 (Manual pages) for details.
    N:
    N: Severity: normal; Certainty: possible
    N:
    Finished running lintian.

    And he tells us that there is no manual page for the binary. As you know, decent people should provide every binary with at least a simple mana that describes what it is. And we do not have it in the package. There are always two ways out: the first is to beg the author of the program to write a man. The second is to write a man and either beg the author to add it to the program, or put it in the package yourself, indicating yourself in copyrights.
    But in general, only the edits that remain for us from working on the package, and if you want to fix something, are a thoughtful reading of Debian Policy .

    What other pitfalls await us?


    The largest and most frequent stone is licensed cleanliness. My friends, you just can’t imagine how many people have run into this. You take the program, put it in a package, and debian-legal tells you: “man, do you know that the src / face / ob / table.cpp file was taken from another program, but you didn’t specify it in copyrights? ? And all the contents of the src / super / karambol / directory are generally distributed under a non-free license. Ah ah ah". But suppose you corrected the error, somehow miraculously persuaded the author of the program to write a free analog instead of non-free code, and included your package in the repository. But after a week, a meticulous user discovers: “dudes, how so. Here, in the messenger, client icons are displayed here. And each logo is always distributed under the license of its program. So you do not have the right to archive the ICQ 6.5 proprietary client icon in the archive. ” Of course, with these words, debian-legal frowns and with a well-aimed kick throws your already accepted package nafig from the repository. That is why, by the way (I promised to tell), the qutIM package was condescendingly accepted into ubuntu, and I'm not even trying to deal with it in Debian until all licensing issues are resolved. For proprietary icons alone, they will drive me with slippers through the entire community.
    Another extremely important problem is, oddly enough, the authors of the programs. Pray for that author whom you will easily convince to accept corrections, additions or something else in an upstream. Because such authors are a rarity. Take, for example, Pidgin src package, admire. It contains a large bundle of patches from the debian community. In upstream pidgin does not take them. And if you try to bring something good to Gnome ... they say that even Torvalds did it with difficulty.
    Still sometimes you may be presented with some incorrect directory placement or the absence or the wrong size / format of some icon for the shortcut to the program in sneakers - lintian loves to swear at this, and you must listen to it first of all. But these are all fairly easy-to-fix bugs, but the first two problems are really serious and durable.

    At this point, I say goodbye to you for several days, the next time I will still tell you how to create my own repository and, if I have time, how to check my packages for kosher using pbuilder.