taskwarrior/package-config/osx

How to make an OSX package
--------------------------

Note: This is being written from the OSX 10.6 perspective, and may therefore
      contain steps that are different for 10.5, although I don't recall any
      actual differences.


0. Philosophy

  Only Fredde tags releases.  We only make builds from tagged commits.  We
  only release builds that build cleanly without errors or warnings.  We only
  release builds that pass 100% of the unit tests.


1. Prerequisites

  You will need an Intel Mac, running OSX 10.5 or later.
  You will need to install the Developer Tools, which are found on your OSX DVD.
  You will need git installed, version 1.5 or later.  See http://git-scm.com
  You will need autotools installed.  See http://www.gnu.org/software/autoconf

2. Get the code

  2.1 Clone the task git repository.  It is important that this is a throwaway
    clone of the repository, because we will do (locally) destructive things
    to it.

    $ git clone git://tasktools.org/task.git ~/task-package.git
    ...
    $ cd ~/task-package.git

  2.2 Making sure you have the right version of the code.  This assumes you are
    building taskwarrior 1.9.2, but any version number is interchangeable.
    Check out the correct branch, and make sure it is sitting at the correct
    commit, via a tag.  Note that while 1.9.2 is a branch name, v1.9.2 is a tag
    name.

    $ git checkout 1.9.2
    $ git reset --hard v1.9.2

    If there is an error in this step, stop, capture the output, and report the
    errors.

3. Build taskwarrior

  3.1 First build the task binary.  Note the "-j 2" tells make to use both cores
    in your dual-core Intel CPU, which means faster compiles.  If you own a quad
    core Mac, use "-j 4".  If you own a single core Mac, just type "make".

    $ autoreconf -f
    $ ./configure
    ...

    If any errors are reported, stop, capture the output, and report the errors.
    
    $ make -j 2

    If there are any errors, or there are any warnings generated by the compiler
    stop, capture the output, and report the problem.  You'll need to watch as
    it builds.

4. Build the test suite

  4.1 The test suite exists to prove that we do not break taskwarrior features
    from one release to the next.  While this is not a perfect solution, it has
    saved us many times from releasing code that is broken.  Build the unit
    tests:

    $ cd ~/task-package.git/src/tests
    $ make -j 2
    ...

  4.2 Run all the unit tests.

    $ ./run_all
    Skipping benchmarks
                                                                                
    Pass:     4241
    Fail:        0
    Skipped:     0
    Runtime:    86

    The output should look something like this, with 0 failed, and 0 skipped
    tests.  If there are any failures or skips, stop and mail the log file,
    named 'all.log' to Paul and/or Fredde.

5. Assemble the parts

  5.1 There is a script that copies all the necessary files (binary, man pages
    etc) in the right place, ready for packaging.  Run this:

    $ cd ~/task-package.git/package-config/osx
    $ ./update

6. Adjust the package details

  6.1 Launch the package manager.

    $ open -a /Developer/Applications/Utilities/PackageManager.app   

  6.2 Close the 'Untitled' window that opens - we will be using a different
    file.  Note that PackageManager is still running - it just has no windows.

  6.3 Using the File -> Open menu, open the file

    ~/task-package.git/package-config/osx/task.pmdoc

    <figure 1>

    This is the file from the last time a package was created.  It needs some
    adjustments.  Start by clicking on the "Taskwarrior x.x.x Distribution" with
    a package icon in the top left part of the window.

  6.4 Click on the "Configuration" button/tab.

    - Change the "Title" to "Taskwarrior 1.9.2"
    - Change the "Description" to "Taskwarrior 1.9.2 install for Snow Leopard"

    <figure 2>

  6.5 Click on "Edit Interface..."

    There are 5 radio buttons on the left hand side - we will visit each and
    make changes.  Click on "Background", make sure it matches the figure.

    <figure 3>

    Click on "Introduction", make sure it matches the figure.

    <figure 4>

    Click on "Read Me", and on the right hand side, under "Read Me Panel", click
    on "File" and select the file:

      /Users/<your-account>/task-package.git/package-config/osx/README.txt

    <figure 5>

    Click on "License", and on the right hand side, under "License Panel", click
    on "File" and select the file:

      /Users/<your-account>/task-package.git/package-config/osx/COPYING.txt

    <figure 6>

    Click on "Finish Up", and make sure it matches the figure.

    <figure 7>

    Close the Interface Editor window (it saves automatically).

  6.6 Back in the "task.pmdoc" window, click on the "Requirements" tab/button,
    then click on the "+" button, and add a requirement rule as shown in the
    figure.  The minimum system should be 10.5.0 or 10.6.0, depending on which
    package is being built.

    <figure 8>

  6.7 Click on the "Actions" tab/button and make sure it matches the figure.

    <figure 9>

  6.8 Click on the triangle next to the "local" item in the "Contents" vertical
    bar on the left to expand and show a folder called "local", with the path
    "/usr/local", but click on the "local" next to the blue radio button, not
    the one next to the folder.  Then click on the "Configuration" tab/button.

    - Change the "Choice Name" to "local"
    - Leave the "Identifier" alone - it is automatic
    - Make sure "Selected" and "Enabled" are checked, but "Hidden" is not

    <figure 10>    

  6.9 Click on the "Requirements" tab/button and make sure it is all blank.

    <figure 11>

  6.10 Click on the blue folder on the left, which is labelled "local", and has
    a path of "/usr/local".  Click on the "Configuration" tab/button.

    - Change the "Install" to /Users/<your-account>/task-package.git/package-config/osx/local
    - Make sure the "Destination" is "/usr/local"
    - Make sure "Allow custom location" is checked
    - Make sure the "Package Identifier is "com.beckingham.task192.local.pkg"
    - Make sure the "Package Version" is 1.0.  If you needed to make a
      subsequent OSX package, *for the same version of task*, then this number
      would be increased to show OSX that this package supersedes the earlier
      one
    - Make sure "Restart Action" is "None"
    - Make sure "Require admin authentication" is checked
    - Make sure "Package Location" is "Self-Contained"

    <figure 12>

  6.11 Click on the "Contents" tab/button.

    - Click on all the triangles in the "local" folder to expand all directories
    - Make sure "Include root in package is not checked"
    - Click on the "Apply Recommendations" button

    Make sure it matches the figure.

    <figure 13>

  6.12 Click on the "Components" tab/button, make sure it is all blank.

  6.13 Click on the "Scripts" tab/button, make sure it is all blank.

7. Building the package

  7.1 Click on the "Build" hammer icon to build the package.

  Provide a filename of "task-1.9.1-sl.pkg" for Snow Leopard (10.6), or
  "task-1.9.2.pkg" for Leopard (10.5), and save it somewhere, for example the
  Desktop.

  All should succeed.  You can click on the "Return" button to end the build
  phase, and you can quit PackageManager, but make sure you save the changes
  you made, because you may need to go through the whole process again, if there
  is an emergency change, or the package is somehow corrupt.

  <figure 14>

8. Test the package

  8.1 Double-click on the package you just created, and install taskwarrior.
    You should see the README file in the UI, and the COPYING file on another
    page.  It should succeed.

  <figure 14>
  <figure 15>
  <figure 16>
  <figure 17>
  <figure 18>
  <figure 19>
  <figure 20>
  <figure 21>

  8.2 Run the following commands to test the installation

  $ /usr/local/bin/task version

  task 2.0.0 built for darwin
  Copyright (C) 2006 - 2014 P. Beckingham, F. Hernandez.

  Taskwarrior may be copied only under the terms of the GNU General Public
  License, which may be found in the taskwarrior source kit.

  Documentation for taskwarrior can be found using 'man task', 'man taskrc',
  'man task-tutorial', 'man task-color', 'man task-faq' or at
  http://taskwarrior.org

  $ man task
  ...
  ...
  task 2.0.0             2013-01-10                task 2.0.0

  The man page should list 2.0.0 as the version number, but the date will be
  different.

9. Email the package to Fredde.

---