Page 1 of 4 123 ... LastLast
Results 1 to 10 of 38

Thread: HOW TO package arbitrary files for your PPA

  1. #1
    Join Date
    Jul 2008
    Location
    $HOME
    Beans
    1,030
    Distro
    Ubuntu 9.10 Karmic Koala

    Post HOW TO package arbitrary files for your PPA

    This tutorial necessarily assumes that you have a PPA (Personal Package Archive) on Launchpad. This involves:

    The official documentation is at https://help.launchpad.net/Packaging/PPA and https://wiki.ubuntu.com/PackagingGuide/Complete.

    The first thing that newbie packagers will notice is that a lot of the documentation assumes that you already have a basic understanding of compiling code, writing makefiles, and the packaging process. It also assumes that you want to package quite complex stuff. All this may be true, but what if you're just trying to package a picture or a bash script?

    This tutoral walks you through every step of doing that basic packaging work.

    ---------------------

    Let's say that you have written a script with the following content:

    Code:
    #!/bin/bash
    echo "Hello, world!"
    You could just save it as /usr/local/bin/helloworld.sh. However, you want to share your fabulous code with the world. This is how you do it.

    First, make a directory for your code. It needs to end in the version number of the software. We will be creating files both inside this directory and also one step above it.

    Code:
    mkdir -p ~/PPA/helloworld/helloworld-1.0/
    cd ~/PPA/helloworld/helloworld-1.0/
    Put your script in that directory.

    Put any documentation you have written in there too.

    If you just wanted to distribute source code, you could at this stage just archive this directory as helloworld-1.0.tgz and send it to people, but we want to go further than that.

    The key to Debian/Ubuntu packaging is the “debian” directory. So let's create it.

    Code:
    mkdir debian
    cd debian
    There are a few files that we need to put into this directory. Let's create them all:

    Code:
    touch changelog compat control copyright install rules
    gedit * &
    All the files will now be open in gedit, in various tabs.

    Go to the changelog tab, and put something like this:

    Code:
    helloworld (1.0-0ubuntu1~ppa1) hardy; urgency=low
    
      * Initial release
    
     -- Joe Bloggs <j.bloggs@example.com>  Sun, 01 Jan 2000 01:01:01 +0000
    The version number should be constructed like this:
    • First, you have the version of the actual software. If it's your own, then you get to decide what version it is at. Let's say it is “1.0”.
    • Then, we put a hyphen and the Debian version number. Since this is your own stuff, you know that it is not in Debian, so we put a zero.
    • The, we write “ubuntu1”, because this is the first version of it available for Ubuntu.
    • Then, we put “~ppa1”, to say that this is the first PPA version.

    Put the same e-mail address that you gave when you created your Launchpad account. It must have a GPG fingerprint associated with it.

    To get the correct date, type “date -R” on the command line. Copy and paste it into the file. In must be in that format exactly.

    Go to the compat tab, and put this:

    Code:
    5
    Go to the control tab, and put this:

    Code:
    Source: helloworld
    Section: utils
    Priority: extra
    Maintainer: Joe Bloggs <j.bloggs@example.com>
    Build-Depends: debhelper (>= 5), cdbs (>= 0.2)
    Standards-Version: 3.8.0
    
    Package: helloworld
    Architecture: all
    Depends: ${shlibs:Depends}, ${misc:Depends}, bash (>= 2)
    Description: Prints a pointless message
     This is a long description of the package and most of
     the stuff it does.  I don't want each line to be more
     than about 50 or 60 characters.  Each line starts with
     a space.
     .
     If I need to make a new paragraph, I have to put a dot
     as you can see above.
    Depending on what you are packaging, you may need to change the section to something other than ”utils”.

    I have added “bash” to the dependencies, because this is a bash script. Specify a recent version of bash if your script uses some new feature of bash. Also specify any other programs which are called by your script. For example, if your script compresses something with bzip2, then you would add “bzip2” as a dependency.

    Go to the copyright tab, and put something like this:

    Code:
    This package was debianised by Joe Bloggs <j.bloggs@example.com> on
    Sun, 01 Jan 2000 01:01:01 +0000
    
    It can be downloaded from https://launchpad.net/~joebloggs/+archive
    
    Upstream Author: 
    
        Joe Bloggs <j.bloggs@example.com>
    
    Copyright:
    
        This software (including its Debian packaging)
        is under the copyright of the above author.
    
    Licence:
    
        This software (including its Debian packaging)
        is available to you under the terms
        of the GPL-3, see "/usr/share/common-licenses/GPL-3".
        You can also use it under the terms of any other GPL version.
    Put the name and e-mail exactly as in the changelog file. Also enter the date in the same way. Include the actual copyright and licence of the software. It must be under a Free licence.

    If you are not packaging your own work, then you have to be slightly more careful, making sure that everything in the package is properly licensed.

    For the “downloaded from” address, you normally put the address that you found the source code at. If it is your own, then you give your website (where people can download the source code). If you have created the code just to upload it to Launchpad, then your full Launchpad URL is probably the most sensible website to give.

    Go to the install tab, and put something like this:

    Code:
    helloworld.sh			/usr/bin/
    As you can see, this is a file that consists of lines which consist of: a file in your package directory, some spaces or tabs, and then the location that they will be installed to. There can be as many lines as you need.

    The proper place for most executable files is /usr/bin/. Do your research to find out where other files ought to go. A GRUB background picture would go in /boot/grub/splashimages/, for example. Make sure that the files installed by your package do not clash with those installed by those in any other commonly used package.

    Go to the rules tab, and put something like this:

    Code:
    #!/usr/bin/make -f
    include /usr/share/cdbs/1/rules/debhelper.mk
    
    binary-install/helloworld::
    	dh_icons
    
    binary-fixup/helloworld::
    	dh_gconf --priority=16
    With most packages, this is a bit complicated. However, since we have nothing to compile, we can use a nice simple rules file like this.

    Save all, and close.

    Return to your terminal, and exit the debian directory:

    Code:
    cd ..
    Into this directory you can now put a file called “README” with any basic notes about the package; a file called “THANKS” with any people who really helped with the software; a file called “COPYING” with the full text of the licence under which the software is released; and a file called “AUTHORS” with the names and e-mail addresses of the people who wrote the software (you, in this case). These are files that are expected to be in any tarball of source code anyway. They aren't specifically to do with Debian packaging. That's why they aren't in the debian directory.

    Now make sure that you have the software needed to work with Launchpad:

    Code:
    sudo apt-get install devscripts dput
    Now let's prepare this stuff for Launchpad:

    Code:
    debuild -S
    That will take a while to complete, and spit out a load of info. If there is an error, then you messed something up. Go to the top of this guide and check that you did each step properly.

    At the end, debuild will ask your for your GPG password so that it can sign the package with your name. This is for security. Launchpad won't accept unsigned stuff.

    If all goes well, debuild will have created several files in the parent of the current directory. In our case, this is ~/PPA/helloworld.

    You can now do “ls ..” or “cd .. && ls” to check that the files are indeed there.

    Let's make sure that your computer knows where to upload the stuff. Do this:

    Code:
    gedit ~/.dput.cf
    In the window that comes up, paste the following:

    Code:
    [my-ppa]
    fqdn = ppa.launchpad.net
    method = ftp
    incoming = ~joebloggs/ubuntu/
    login = anonymous
    allow_unsigned_uploads = 0
    
    [DEFAULT]
    default_host_main = my-ppa
    Change “joebloggs” to your actual Launchpad ID. Save and close.

    Now upload your work to Launchpad:

    Code:
    dput my-ppa ~/PPA/helloworld_1.0-0ubuntu1~ppa1_source.changes
    As you can see, you have to point the dput command at the .changes file that you have just created. It won't upload just that file though; it will also upload the source-code tarball.

    A few minutes later, you'll get an e-mail from Launchpad saying that the package has been accepted and added to the queue. It could take anything from a couple of minutes to a couple of hours for your source code to be turned into an actual .deb package and be available in your PPA.

    Relax and have a cup of tea, and think about which friends you'll brag to about your new techno-skills.

    ---------------------

    There is more to learn than this, but my assumption is that you need the psychological boost of successfully packaging something, and that after all this you will look into learning how to tweak this for more complex tasks.
    Last edited by Pro-reason; October 1st, 2008 at 01:59 AM.
    If people were nicer, I'd answer more queries here!

  2. #2
    Join Date
    Dec 2007
    Location
    Illinois
    Beans
    49
    Distro
    Ubuntu 8.04 Hardy Heron

    Re: HOW TO package arbitrary files for your PPA

    Is it really necessary to create a whole .deb package to distribute some arbitrary files or a shell script? Seems like a lot of work where a simple FTP would do the trick.

    Or, if you're intent on using Launchpad, why not start a new project (named, perhaps, "[username]s-files"), and use the bzr version control to upload and distribute your files.

    It just seems like a lot of extra work to create all of the extra debian/ files. Also, having a more general interface (FTP or bzr) allows users more flexibility in downloading and installing your files.
    Scott Wegner
    automaticable.com

  3. #3
    Join Date
    Jul 2008
    Location
    $HOME
    Beans
    1,030
    Distro
    Ubuntu 9.10 Karmic Koala

    Re: HOW TO package arbitrary files for your PPA

    Quote Originally Posted by swegner View Post
    Is it really necessary to create a whole .deb package to distribute some arbitrary files or a shell script?
    Yes. Look in Synaptic. There are hundreds of packages that involve no compiling. They contain images, dictionaries, scripts, documentation, or are even empty metapackages. If you disagree with my tutorial, you're disagreeing with Ubuntu!

    Using bzr instead of a repository excludes the vast majority of Ubuntu users. Ubuntu software is centred around APT repos. Your approach is more appropriate for Slackware.
    If people were nicer, I'd answer more queries here!

  4. #4
    Join Date
    Dec 2007
    Location
    Illinois
    Beans
    49
    Distro
    Ubuntu 8.04 Hardy Heron

    Re: HOW TO package arbitrary files for your PPA

    Your approach seems most appropriate for files and packages you assume will be universally applicable and well-distributed. If you are just sharing "arbitrary files", then sometimes it doesn't make sense to create a whole package for it. For example, does it make sense to download via apt "someguy-resume", or just grab the resume from a website or FTP?

    It's true that there are many packages which already exist that don't need to be compiled. However, these generally relate to some sort of existing functional package (themes for GDM, documentation for GIMP, screensaver packs for xscreensaver, etc.). These packages are generally installed at some system location that makes sense for the application. But individual users' files should really live in the home directory, and shouldn't need administrator privelages to add/delete/modify.

    The other main downside is the cost of set up. It does take quite some time to register for Launchpad and a PPA, set up a development environment, and create the packaging files to get them ready to upload. Then you require users to actually add your PPA to their sources list (which implies that they really need to trust you), and then finally download the package.

    In general, I think in determining whether files are appropriate for a PPA, you need to consider the scope and audience of the files. I agree that there are instances where this could be beneficial, but not as a general case. If the files are mostly for personal use, then why go through the trouble?
    Scott Wegner
    automaticable.com

  5. #5
    Join Date
    Jul 2008
    Location
    $HOME
    Beans
    1,030
    Distro
    Ubuntu 9.10 Karmic Koala

    Re: HOW TO package arbitrary files for your PPA

    Quote Originally Posted by swegner View Post
    If the files are mostly for personal use...
    What on earth are you talking about? Please go away.
    If people were nicer, I'd answer more queries here!

  6. #6
    Join Date
    Jul 2006
    Location
    Hertfordshire
    Beans
    454
    Distro
    Kubuntu 9.04 Jaunty Jackalope

    Re: HOW TO package arbitrary files for your PPA

    Good HOW-TO, thanks for that.

    I'd just point out that the "dh_make" script provided by the dh-make package will nearly half the steps you've given for creating the package.

    A quick and dirty run-down on how to use it:

    Code:
    $> sudo apt-get install dh-make
    $> mv test test-1.0.0 && cd test-1.0.0
    $> dh_make --single --native --email seanhodges@bluebottle.com
    
    Maintainer name : Sean Hodges
    Email-Address   : seanhodges@bluebottle.com 
    Date            : Mon, 29 Sep 2008 18:18:21 +0100
    Package Name    : test
    Version         : 1.0.0
    License         : gpl
    Type of Package : Single
    Hit <enter> to confirm: 
    Currently there is no top level Makefile. This may require additional tuning.
    Done. Please edit the files in the debian/ subdirectory now. You should also
    check that the test Makefiles install into $DESTDIR and not in / .
    
    $> rm debian/*.ex debian/*.EX
    $> ls
    debian  test.sh
    $> ls debian/
    changelog  compat  control  copyright  dirs  docs  README  README.Debian  rules
    This would avoid people needing to create all the necessary files, and set up things like the package compat value.

    Of course, you may already be aware of this and gave the long-winded approach to describe the package files in more detail. Either way, I love these "get started quickly" HOWTO's, and this one is pretty easy to follow.

  7. #7
    Join Date
    Jul 2008
    Location
    $HOME
    Beans
    1,030
    Distro
    Ubuntu 9.10 Karmic Koala

    Wink Re: HOW TO package arbitrary files for your PPA

    Quote Originally Posted by SeanHodges View Post
    Good HOW-TO, thanks for that.

    I'd just point out that the "dh_make" script provided by the dh-make package will nearly half the steps you've given for creating the package.
    Yes, I started by using those scripts that create the necessary structure. However, you then have to go back over it, deleting unnecessary files and editing the others. It doesn't actually set things up the way you need.

    I would have appreciated a guide that explained things from the bottom up, rather than cutting from the top. A guide that explained each file necessary to package arbitrary files, and nothing else. So, I wrote that guide.
    If people were nicer, I'd answer more queries here!

  8. #8
    Join Date
    Jul 2006
    Location
    Hertfordshire
    Beans
    454
    Distro
    Kubuntu 9.04 Jaunty Jackalope

    Re: HOW TO package arbitrary files for your PPA

    Quote Originally Posted by Pro-reason View Post
    Yes, I started by using those scripts that create the necessary structure. However, you then have to go back over it, deleting unnecessary files and editing the others. It doesn't actually set things up the way you need.
    Personally I find it quicker and less error-prone to edit some skeleton files than create them from scratch each time, but the scripts are probably a matter of taste, especially when getting used to the packaging process.

    If your intention was to explain the files from the bottom up, then I agree avoiding scripts like dh_make was the better strategy.

  9. #9
    Join Date
    Apr 2008
    Location
    Ohio
    Beans
    202

    Re: HOW TO package arbitrary files for your PPA

    Now signing changes and any dsc files...
    signfile yt2mp3_1.0-0ubuntu1~ppa1.dsc Andrew Kiss <xanga9885@hotmail.com>
    gpg: skipped "Andrew Kiss <xanga9885@hotmail.com>": secret key not available
    gpg: [stdin]: clearsign failed: secret key not available
    debsign: gpg error occurred! Aborting....
    debuild: fatal error at line 1250:
    running debsign failed
    andy@comp ~/Projects/yt2mp3/yt2mp3-1.0 $
    ...what?

  10. #10
    Join Date
    Jul 2008
    Location
    $HOME
    Beans
    1,030
    Distro
    Ubuntu 9.10 Karmic Koala

    Re: HOW TO package arbitrary files for your PPA

    Quote Originally Posted by RATM_Owns View Post
    ...what?
    Have you registered a public encryption key for the address “xanga9885@hotmail.com”? This is required for security reasons.
    Last edited by Pro-reason; October 5th, 2008 at 01:43 PM. Reason: adding link
    If people were nicer, I'd answer more queries here!

Page 1 of 4 123 ... LastLast

Tags for this Thread

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •