 Okay, this talk is Packaging for Beginners by Gagai Nagi, also known as Algernon. Yeah, something like that. Well, the thing here is 45 minutes is very short for teaching anyone how to package even the most simple package properly. So, instead of, well, trying to teach you something which is impossible, I will try to show a few examples which hopefully will show you how packaging can be fun and rewarding. And in order to do so, I will start with a little story. A little story happens in a wonderful and magical world, where we saw the earth, and in this little world there is a boy who has a fascination for computers. It just so happens that on his computer he has a system, a free system with source code, so many that he could spend centuries reading it, and he would still not be bored. Well, as it happens, this boy over the years developed the fascination for developing free software for the system, and one day when his little sister entered the room and asked him to write her a pony, he did so, and this program was so awesome that years later his sister, who is using the same system, wanted to surprise his brother, who in the meanwhile became a Debian developer, and she wanted to package this little pony, and this is what I will show you how she did so. But first, let me show you the pony. It's a very simple program. Your standard configure make, make, install, style, thing, configure, make, and it does the rest, and now they show you what it does. Well, I already built it, and this is the pony. Awesome isn't it? Well, this is the program we will package. Little sister already set up a directory where this program is. Well, that's the source code. So how do we start? We have an upstream source code. We can build it. We can install it and it just works, but we want a Debian package. So we do the obvious and extract it if I remember the command. Well, same thing over again. There we go. Little sister read somewhere that in order to build a Debian package, you need to invoke the dpkg-build-package command. Wow, okay. Just a second. We're in the podium, so you won't hide it. Sorry. And you won't have the projector in your eye. Yeah, that's a great relief. Well, as you see, we ran the package, and while it kind of threw us an error, that it can't find the Debian slash changelog file. Maybe we should make one. We could look at another package or copy it, but instead I will cheat a little bit and invoke this command called dch, which is supposed to be used to update the Debian changelog files. It's also very helpful because it immediately told us that we can use the dash-create command to create that file. And when I use that, it can't find the directory, so let's make it and run it again. There we go. Oh, well. One moment. I'll fire up a different editor. Oh, this is a little bit better. So this is the template for a changelog. We fill it out. It's version zero, and we're supposed to release it into a stable. I could also fix the name, but that would take a little while because I didn't figure out how sister is called. So let's just leave it with that. Okay, so now we have a changelog. Let's see what build package throws in our face again. Well, okay. The main error here is that there is no Debian control file. This Debian control file is the file that tells the build program certain information about the package, such as which section it is in, which priority it has, what is the source file called, what binary packages it builds, because you can have a single source package and build as many binary packages from it as you wish. In our example, we want to build one simple binary package. So we will write the control file accordingly. And as we do so, I will try to explain what different fields mean. Okay, so first, the Debian control file looks a little bit like an email. It has fields and it has values. The first block of fields describes the source and as such, we tell it that the source is called pony. And well, a pony is not really useful, so we put it in the game section and it's not that important the package, so we set the priority to extra. For a start, let's say that's enough for a simple source. And we need to build a binary package and we want to call it pony. And since it's a compiled program, we need to set the architecture to any. You can set the architecture, well, if it's a compiled program, it's best to set to any in the beginning. If it's a script or something like that, you can set it to all, which means it will be architecture independent. If you know it will only compile on a certain subset of architectures that Debian supports, you can list that there. The next thing is coming up with a description for this package and, well, throws a pony on the screen. We also need a long description and let's see if this is enough. Oh, much better, thank you. Well, it doesn't complain about the control file anymore. Now it complains that it can't find Debian rules. Well, what is that file? Debian rules is the file that tells the DPKG build package how to assemble the Debian package we want to build. It needs to have a... Well, basically it's a make file. It needs to have a certain set of targets to build a package, to install it to the right place and to build a Debian package out of that whole thing. I will not go into details how this works. I will just show a very, very simple example, which should be enough for the vast majority of simple packages, such as the one we are packaging now. And when I mean simple, I really mean simple. First, the shebang line. And this is the trick. Let me spend a few moments explaining what this does. There's a helper package called Depthelper, which is meant to make it easier to package software into Debian. And it has a so-called short mode, or DH mode, which pretty much works on a do-what-I-mean basis. And it automatically tries to figure out what you want. It looks at the source code, figures out that, hey, it's built with AutoConf and AutoMake. I know how to build that. I know how to install it. And pretty much it does everything for you. Now, I must stress that using this is convenient, but if you end up packaging, or better say, when you end up packaging, in the long run, you really do want to know what is behind these commands. I will not go into that today, because that is a very long story and it is well-documented. Let's just say that this works and is easy, and we make this file executable and see what happens. Wow, a lot of things happen. It's just building the package, but it's also complaining about this compatibility level 5 or something. What the hell is that? Well, thankfully, we have a man page, and we can search for Compat. There is this Tebian Compat thing, so I will cheat a little bit again, and instead of going through the man page, I will tell you that in order to use the short form, you have to put an 8 into this dbian slash Compat file, because step helper has different compatibility levels, so it can remain backwards compatible with former versions. So we do something like this and try again. It builds again, and magically it stopped complaining. Well, it does complain about my keynote phone, but that's expected because it's not on the laptop. Let's see what happened. Well, look at that. What we have here. We have a package, so let's try installing it and see if it works. It works. Magic. We know we're near finished yet. Not by far. This is just a package, but once you start to use tools which help you make your package better, such as Lintian, well, this will be embracing. Yes, it is embracing. Let's try this so it doesn't try to sign it. Missing maintainer. Why didn't I notice that? Okay, let's fix that. Well, as it turns out, every package needs to have a maintainer. So we write one. This will be me for the moment, and rebuild as usual, let's say. Well, this takes a little while. Oh, my God, that's a lot of errors and warnings. Well, let's go over these warnings and what they mean. First of all, each package should have a build dependency field in DBM control. That field describes what other packages this one needs in order to be built. Every tool you use during the build, except a few, and everything else the package depends on during build, needs to be listed there. So, for example, since we use Depthalper, that needs to put into the build-upends field. And since we use version 8 of Depthalper, we need to make that build dependency version. I didn't tell it in the beginning, but, well, never mind, we'll get to that later. Let's just start Depthalper for a start. Build, Depthalper, and rebuild. Let's see what it says now. Well, it's a little bit less errors this time, and yes, another thing I forgot to put into the control file is the Depends field. Every binary package, or well, every package where it makes sense, needs to be a Depends line, which is a bit similar to build-upends, except that it lists the packages. The package depends on once it is installed. So, for example, we need not put Depthalper there because the package doesn't use it. There is a trick when using Depthalper, well, basically any other helper, that can figure out what are the libraries one program is linked against. And I will show you the trick right now. So, we need a Depends line. If we put this here, while building the package, this will be expanded to the list of the libraries, the binary we just built depends on. We don't need to know, and we don't need to explicitly list all that stuff here. So, this makes it a lot easier. And we rebuild again and see what happens. In the meantime, I'll run Lintian again. So, this... Sure. There's all these Lintian warnings you've got. Is there a web page that lists what these mean? Or is there... Yeah, there is a web page somewhere, which I forgot, but you can do Lintian info, and it will hopefully tell me how to proceed, or maybe not. I think it was the... Oh, okay. Yeah, indeed, this tells a lot more about what each tag means. Yeah, good idea is to go through these descriptions when packaging a piece of software, and you can work your way up from doing something simple like we did to having Lintian clean package, which is a pretty requirement for any package entering DBA nowadays, thankfully. And yeah, I think that was most of what I wanted to tell. Basically, as I've shown, doing a very simple package is unbelievably easy. And we have a lot of tools which help make this package better, which have both good documentation, and they have very nice output, which helps you make the package better, and you can make your way up from there to end up with a really nice package. So if there are any questions, then please shout. If I said anything stupid, then please beat me to the ground. I think one of the most important points that you illustrated is that every developer or maintainer or whatever will have his different way of doing things, and everyone will know a different set of tools, and there is no single way to show things, no simple way to present... That is correct. As many developers, there are as many ways to do packaging. There are common points, but yeah. I have another question. Is there a way to know what's inside the depth package that you created? Yes. Well, the very easy way is to launch Midnight Commander and just look inside it. There are certainly better ways, but this is convenient. Basically, the depth package has two parts. It has the real contents, which at the moment is our binary package, binary software, and a little bit of documentation which at the moment consists of the D-Bend changelog. The other part of the depth package is the various control information. The control file we created, or at least part of it, as you can see somewhere here, it depends on... In the source, we used a variable there, and the build process expanded it to what you see above. The depth package contains this, contains various other files such as pre- and post-installation scripts and... Thanks, Aya. Any other questions? Hi. I'm new to contributing, and before coming here, I tried to learn how to package stuff. The only problem I have with this is because there's lots of information around and there are lots of ways of doing it, so I was wondering if someone from the audience or you perhaps can personally recommend a tutorial which has a uniform method of doing it because there is lots of information and I can't make sense, right? Much like, I think, the key and art of packaging, so as to speak, yeah. Yeah. I would suggest, first, forget about documentation at the start because, as you said, there is a lot of it. Instead, I would suggest have a look at packages, a few simple ones and try to copy it and try to change it until it works for what you want to package and read the documentation when you encounter a problem or if something really doesn't make sense, then you can find the appropriate documentation either in the DBM policy or the new maintainers guide or the developer's reference or Lucas, I think, now bombs packaging tutorial. Both of these documents are awesome but all of them are pretty big and hard to digest at first, so I would suggest do first, read after. However, when you are about to upload a package to the DBM before that, make sure that it's really in a good shape. I just want to quickly say that the new maintainers guide has been being revised a lot in the past year and two years and I think it's actually a very high quality. The most important thing with any piece of documentation is to stick with it from beginning to end and not to swap from one tutorial to the other, which I do all the time. So, new maintainers guide. One other piece of advice I might give is to look at a recent package version. If you look at several different ones, they all look rather different and they're very confusing and you wonder why there are different ways of applying patches. So, use a recent and small package. Two comments. First of all, after that I will show you a few more additions to the packaging and the new maintainers guide is really recommended and even experienced developers walk with it because they forget stuff, sometimes forget the right syntax or sometimes just want an example. So, it's good for beginners and experienced people. I would read it once, although you might not understand everything, then start to package and return to the guide because once you read it, some of the bits will already be in your head and you can return to a specific part. It will be easier that way. After I know other questions, then I'll give the... I'm the intruder here. I wrote the new maintainers guide. I first let others speak for it. Just listen to Google. Type how to build the Debian package into Google and the first Debian.org result is okay. It will work. Yeah, you're working with Michel? Yes. Perfect. The layout is English. It's just a little bit Hungarian. So, okay, Mike walks. I'll do a few additions to the tutorial we just had. Please be patient with me because it's in Hungarian keyboard with English layout and it's not my laptop. So, I wanted to show you, first of all, a few additions. One of them. Let's see where we are. Where's the minus key? Oh, thank you. Okay, the first... It's really hard when you don't see what you type. First of all, you can get information about the package without checking its contents with the package and you can see, take your trick, that this was the line that we had with Schlib's depends. Another one that all the dev files are actually archived files and sometimes have sub-archives. So, you can use anything that shows these formats to show the package contents. But another option is, again, to ask the package to help you and get a look at least of the files that would be on the file system which are not the control files. As we saw before, there are a few parts that are not shown here, which are the control files, the MD5 sums, and the maintenance scripts, the post install, pre-install, and the same for removal. Regarding the rule files, this is... Okay. This is compatibility version 8 of the rule files and for my taste, it's a bit too automatic and too short. I prefer to work with the largest or more expanded version. I'll just do a build for a second. You can see that during the process, there are a lot of DH programs that are run. So, this is what the black box actually does. It runs a lot of smaller scripts, which each one of them has a unique role. I'll take an example... Yes, yes, you are correct. I'm just used to VM. Okay, this will be the previous version of the rule files and actually has all the targets that the automated DH actually runs. It has a few targets, the main ones... This is a template, so this is the reason for all these lines with hash before them. We have the build target, which calls build stamp. I won't go with the whole rules files and how it works, but just to give you a general orientation of the file. The main target we have here is build, clean, install, and usually binary, which actually causes the package, takes the files into a Debian package. There's a way, as we saw earlier, the Debian rule files actually has execution permissions, so we can run it and it will work, and we can specify one target, so we won't do the whole process, but just the one we want. Let's do clean first and then... For example, if we have build problem of the package, we won't need the whole process just to figure out where's the build problem, because if the build fails, the rest will fail also. This will be an easier way to find why the program is failing. In this case, it won't fail, but it will help us debug. Then we can run the install part. This would be a good option to explain about fake root. Usually installation is done as root because the make install program thinks we are going to install to the real location, which is usually slash USR bin or whatever directory, and they're all only writable with root permissions. To circumvent this problem, we use fake root, which tells the program, it's okay, you're root, you can write to that location, and the program thinks, okay, I'm root, I'll just write it, and this way we can package stuff in our home user, whatever directory we have, without actually messing with the actual system we're using. This is a very healthy situation for building, because sometimes you might have a package install its files and overrun the system's programs or mess with the configuration or a lot of things that you want to do on the actual system. So running it as your own user is the best practice. Just going up to the history, okay. I'll show you. The actual files are written inside the Debian directory, and the files are written to the directory called the same as the package, in our case pony, and you would see it has also the Debian part, this one, and also the user part. This is the actual files that are going on the file system, and this is the Debian control files. If you use the command, the find command, to see the layout, and then compare it, you see it's actually the same, okay. Well, except for the Debian directory, I mean this one, which the d-package-c won't show you. Well, with more complex packages, we actually have another directory that all the files are written to there and then move to another place depending on which sub-packages they should relate to. A few more things I wanted to show you. First of all, during the changelog file, we have this part. This is the best way we use changelog to close bugs. Probably you won't encounter it first, but when your package will be uploaded, I hope you won't get any bugs, but in the case you will, the next changelog entry should mention closes and the bug number. The format here is really important, so if you forget the two dots or the hash sign, it won't close the bug. The plus side is if you write the format correctly, the bug will be automatically closed upon upload and you won't need to do anything manually. We have a very similar format if you want to close bugs in Ubuntu. So when the package moves from Debian to Ubuntu, it can also close bugs in Ubuntu. For example, this is the way I also monitor my bugs in the bugs of my packages in Ubuntu and if there's a fix, I just mentioned bugs from both bug tracking systems. We can use the DCHO, let me first, the previous part. We had install and then, just to show you it works. So we don't have any DEB file and this would actually create a DEB file. So we can do the whole build process step by step and to see what it actually does and it's easier to repeat steps after we make fixes instead of rebuilding the whole package. Sometimes the compilation part takes a lot of time and there's no need to repeat it time over time if you're only changing, for example, where the files will be. There's a few tools that could help you. They come from, it's called DEB scripts package and it has a lot of helper scripts which would make your life easier. One of them you saw earlier which is called DCH and for example, if you want to add an item to the changelog, again, sorry for the... Yeah, let's try again. Okay, so we see it already opened the changelog file. It added an asterisk so we can start our own new entry and it also updated the timestamp. It's very easy and very convenient. Next, we would decide we want to have a newer version of Pony and we would use DCH-i, i is increment and we'll get a newer version. Okay, so we jump from Pony version 0 to Pony version 1. Another thing, sorry, I'm not used to it. Okay, we'll start with version 0. Sometimes the package, the app swim we have is Debian-specific one and sometimes it's a more general program which can go to a lot of distributions and on top of that we'll actually add the Debian directory and all its files. So we want to have a separation between what came from AppSprim and what came from Debian and if we take a look again at the result file we can see that we only have a Debian package and the AppSprim source. In this case and this version in Scheme, actually we choose 0, we can only have these two. This means the package is Debian-specific. It usually goes for packages written by Debian people, for Debian and in most cases they are irrelevant to other distributions. If we want a general package we need to add a version to the package. Well, the 0 here means the AppSprim version and the minus one or actually the one means the Debian subversion. So when the next time we try to increment the version here it will go to 0-2. So it's the same AppSprim version but Debian has another version of the package. So let's say a new version or better yet just fix something. So the next time actually then we'll get another error probably. One minute, okay let's do it fast. So this time you can see that for version 0-2 we got a binary package which has a different name and I'm missing something, yeah. And a towerball just for the version. So don't mix between this one and this one. They are not the same. Just to show you the difference. Okay, this will be the AppSprim files. You could see this is the source and that would be only, yeah, okay. No, excuse me because we have to rename the source the AppSprim file and we won't have time for that, yeah. Quick questions before we finish? Yes. When using the TAP Helper version 8 can you selectively override targets? Yes, you can but it's a bit more complicated and this is the reason I prefer the previous version because it's much more simpler to have changes in it. Okay, especially for beginners and they can just go to the exact point of the problem and do the change except instead of trying to figure out how the automated system works and where to put the right hook so something else will happen. Okay, time's up. Thank you. Thank you very much.