Difference between revisions of "Applying Patches"

From WebOS Internals
Jump to navigation Jump to search
(d)
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{reorganize|This page is deprecated}}
 
==Introduction==
 
==Introduction==
  
Line 19: Line 20:
  
 
* ipkg-opt update
 
* ipkg-opt update
* ipkg-opt remove quilt perl libdb gdbm util-linux-ng e2fslibs ncursesw ncurses
+
* ipkg-opt remove quilt perl libdb gdbm util-linux-ng e2fslibs ncursesw
 
* ipkg-opt install quilt-lite
 
* ipkg-opt install quilt-lite
  
 
Alternatively, the setup script below will prompt to uninstall quilt, perl, etc ..., and install quilt-lite, if quilt is installed.
 
Alternatively, the setup script below will prompt to uninstall quilt, perl, etc ..., and install quilt-lite, if quilt is installed.
 
  
 
==Setup Procedure (Scripted)==
 
==Setup Procedure (Scripted)==
Line 182: Line 182:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
 +
==Quilt Commands==
 +
 +
Other commands when using Quilt-Lite:
 +
 +
Please feel free to add/edit this section. I am not an expert, these are commands that I found by accident when i misspelled delete.
 +
 +
<pre><nowiki>
 +
quilt
 +
        add
 +
        applied (shows applied/installed patches)
 +
        delete  (removes a patch from quilt series ex: quilt delete *name of patch*)
 +
        diff
 +
        edit
 +
        files
 +
        fold
 +
        fork
 +
        graph
 +
        grep
 +
        header
 +
        import  (downloads patch from git ex: quilt import *name of patch*)
 +
        mail
 +
        new
 +
        next
 +
        patches
 +
        pop
 +
        previous
 +
        push  (installs patches from quilt series one at a time. quilt push -a installs all patches)
 +
        refresh
 +
        rename
 +
        revert
 +
        series (shows all downloaded patches.)
 +
        setup
 +
        snapshot
 +
        top
 +
        unapplied
 +
        upgrade
 +
 +
</nowiki></pre>
  
 
==Information for developing patches==
 
==Information for developing patches==
Line 188: Line 227:
 
Before you can commit to gitorious you need to [http://gitorious.org/users/new create an account].  
 
Before you can commit to gitorious you need to [http://gitorious.org/users/new create an account].  
  
Next you'll need to generate a public key and share that with gitorious.org, your public key is how gitorious.org authenticates you and checks if have the permissions required to do a commit to a given repository.
+
Next, you'll need to create a public/private key pair, and the easiest way to do this is with openssh.  If you want to create a pair with windows, there are PuTTYgen/Pageant instructions below under "Alternate Windows Method", but the following may be easier.  After you generate a public key you'll share it with gitorious.org; your public key is how gitorious.org authenticates you and checks if have the permissions required to do a commit to a given repository.
 +
<pre><nowiki>
 +
ipkg-opt update
 +
ipkg-opt install openssh # *see Note Below
 +
sudo ssh-keygen -t rsa # follow the prompts, ensure you're saving to /var/home/root/.ssh
 +
cat /var/home/root/.ssh/id_rsa.pub  # copy the output and paste it into gitorious key manager
 +
</nowiki></pre>
 +
<nowiki>*</nowiki>There's been some work to get dropbear working, but this tutorial assumes you have openssh installed. For information about dropbear and ssh keys, see [http://tumblelog.jauderho.com/post/151678345/using-dropbear-with-git this page]
 +
* Don't forget to upload your public key from the last statement above to gitorious.org
 +
 
 +
 
 +
Next, you'll need to ensure you have your environment properly configured.
 +
 
 +
<pre><nowiki>
 +
echo $GIT_SSH # Should be /opt/bin/openssh-ssh
 +
</nowiki></pre>
 +
 
 +
If the output of this command are anything other than /opt/bin/openssh-ssh, you'll need to update /etc/profile.d/optware.  Add
 +
 
 +
<pre><nowiki>
 +
export GIT_SSH=/opt/bin/openssh-ssh
 +
</nowiki></pre>
 +
 
 +
To the top of the /etc/profile.d/optware.
 +
 
 +
Now you should be able to follow the steps below and contribute your code to gitorious.org.
 +
 
 +
 
 +
'''Alternate Windows Method'''
 +
 
 +
The only reasons you might want to pursue this method is if you want to generate a ssh key pair on a Windows box.
  
 
Getting your key on window
 
Getting your key on window
Line 204: Line 273:
  
 
* After which you will need to run [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Pageant] on your pc. Pageant holds your private key in memory for PuTTY to use.
 
* After which you will need to run [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Pageant] on your pc. Pageant holds your private key in memory for PuTTY to use.
 
* To commit changes to gitorious.org from the pre you will need to install openssh on the device.
 
<pre><nowiki>
 
ipkg-opt update
 
ipkg-opt install openssh # since dropbear doesn't do agent forwarding, you need to use openssh
 
</nowiki></pre>
 
 
Actually, it is possible to use dropbear with git but requires [http://tumblelog.jauderho.com/post/151678345/using-dropbear-with-git some hackery].
 
 
As an alternative, if you don't use the keys for anything else you could just generate them on the pre after installing open-ssh
 
<pre><nowiki>
 
sudo ssh-keygen -t rsa # follow the prompts
 
cat ~/.ssh/id_rsa.pub  # display the public key you need to paste into gitorious
 
</nowiki></pre>
 
 
* Don't forget to upload your public key to gitorious.org after generating it.
 
Now you should be able to follow the steps below and contribute your code to gitorious.org.
 
 
* If you find yourself getting errors about your public key when you try to push changes, check to make sure your keys are under /var/home/root/.ssh/ and not under your regular user account.
 
  
 
===Creating a patch===
 
===Creating a patch===
Line 278: Line 328:
 
git remote add origin git@gitorious.org:webos-internals/modifications.git
 
git remote add origin git@gitorious.org:webos-internals/modifications.git
 
</nowiki></pre>
 
</nowiki></pre>
 +
*This will destroy your ability to actually pull down updates, so you'll need to modify the /opt/src/modifications/.git/config to contain:
  
 +
<pre><nowiki>
 +
[branch "master"]
 +
        remote = origin
 +
        merge = refs/heads/master
 +
</nowiki></pre>
 
* Finally, push your changes up to gitorious.org
 
* Finally, push your changes up to gitorious.org
  

Latest revision as of 17:32, 22 November 2010

Warning: This page is deprecated

Introduction

We cannot legally redistribute Palm source code (it is copyrighted code, and is not released under an open source license) therefore we need to manage our modifications as patches. Since these patches will come from many different places, and will need to be removed before each OTA update and then reapplied after-wards, we need a procedure and tools for doing this. This page documents this procedure.

Before asking questions about this procedure, please read the following documents fully:

An introduction to Quilt can be found at http://www.suse.de/~agruen/quilt.pdf

The manual for quilt is at http://linux.die.net/man/1/quilt


Upgrading from quilt to quilt-lite

If you have performed these instructions before the 8th Aug 2009, you will have installed a very heavyweight version of the quilt package which has a dependency on a very large perl package.

This dependency has been removed in a new quilt-lite package, which saves 26MB of space in /var as a result.

You can switch over to it as follows:

  • ipkg-opt update
  • ipkg-opt remove quilt perl libdb gdbm util-linux-ng e2fslibs ncursesw
  • ipkg-opt install quilt-lite

Alternatively, the setup script below will prompt to uninstall quilt, perl, etc ..., and install quilt-lite, if quilt is installed.

Setup Procedure (Scripted)

The process of setting up quilt has been scripted. The script performs the following actions:

  • Installs (or upgrades) git and any dependencies
  • Installs (or upgrades) quilt (actually quilt-lite, a version of quilt that does not depend on perl) and any dependencies
  • Configures quilt to store patches in /opt/src/patches
  • Creates (or updates) a local clone of the webos-internals modifications repository

Each step is only performed if necessary. Please note that ipkg-opt needs to be installed. The instructions are found here.

To get run the script, log into your Pre, gain root privileges and run the following commands:

 cd /tmp
 wget http://gitorious.org/webos-internals/bootstrap/blobs/raw/master/quilt-bootstrap.sh
 sh quilt-bootstrap.sh


Setup Procedure (Manual Process)

(Note: Even though you may have previously installed the optware quilt patch manager, it won't damage anything to follow the Setup procedure. Alternatively, if you KNOW FOR SURE these are installed and your packages are up-to-date, you can skip to Importing and Applying Patches).

  • Log into your Pre, and gain root privileges. (Note: This command is not required when using the emulator)
sudo -i # Yes, the -i is important. 
  • Put your Pre in to Read Write Mode
mount -o remount,rw /
  • Ensure that you are set up for optware package installations, and make sure you have the latest package index:
ipkg-opt update
  • Install the 'quilt-lite' package, which will be used to manage the patches you apply, and the 'git' package, which will be used to download existing patches from the modifications repository:
ipkg-opt install quilt-lite git

(If you already have those packages installed, repeating this step will not cause any harm.)

  • Create a directory in which 'quilt' will manage your chosen modifications:
mkdir -p /opt/src/patches
  • Edit /opt/etc/quilt.quiltrc to point quilt to that directory:
sed -ire 's|^[\s#]*QUILT_PATCHES=.*|QUILT_PATCHES=/opt/src/patches|' /opt/etc/quilt.quiltrc
  • Delete any existing webos-internals modifications directories
rm -rf /opt/src/modifications
  • Clone the webos-internals modifications repository:
cd /opt/src
git clone git://gitorious.org/webos-internals/modifications.git


Importing and Applying Patches

  • Ensure your list of modifications is up to date
cd /opt/src/modifications
git pull
    • If you find yourself getting errors when you try to pull with the above command then you will need to modify your .git/config file
sudo vi /opt/src/modifications/.git/config
    • Your [master] section should look like the following
[branch "master"]
        remote = origin
        merge = refs/heads/master   
  • Browse the set of available patches. Each patch should have a description at the top.
find /opt/src/modifications -name *.patch
  • Choose a patch from the modifications repository and import it into your own patches directory:
cd / # It is *very* important to be in the / directory when you run quilt.
quilt import /opt/src/modifications/application_name/patch_name.patch   # Note that you need to replace application_name and patch_name here.
  • Verify that quilt has imported the patch successfully:
# You should still be in the / directory to run quilt.
quilt series  # you should see your patch listed in here
  • Instruct quilt to apply your patch
# You should still be in the / directory to run quilt.
quilt push
# Use this to push all patches at once.
quilt push -a
  • If everything worked correctly, the patch should now be applied. You will usually need to restart the luna service on the Pre to see the effect of patches to applications. Here's how to initiate a rescan.
luna-send -n 1 palm://com.palm.applicationManager/rescan {}

If that doesn't work, try a service restart with:

stop LunaSysMgr && start LunaSysMgr

And if all else fails, simply reboot:

reboot


Listing Applied Patches

cd / # It is *very* important to be in the / directory when you run quilt.
quilt applied


Removing All Patches

Before you accept an over-the-air (OTA) update, you should remove any patches you have applied. Luckily, using quilt makes this very easy.

  • Remove all patches:
cd / # It is *very* important to be in the / directory when you run quilt.
quilt pop -a


Reapplying all patches

After your OTA update is complete, you will want to reapply any patches you have selected. This may or may not go smoothly.

  • Apply all patches:
cd / # It is *very* important to be in the / directory when you run quilt.
quilt push -a
  • Put your Pre back in to Read Only mode
mount -o remount,ro /


Quilt Commands

Other commands when using Quilt-Lite:

Please feel free to add/edit this section. I am not an expert, these are commands that I found by accident when i misspelled delete.

quilt
        add
        applied (shows applied/installed patches)
        delete  (removes a patch from quilt series ex: quilt delete *name of patch*)
        diff
        edit
        files
        fold
        fork
        graph
        grep
        header
        import  (downloads patch from git ex: quilt import *name of patch*)
        mail
        new
        next
        patches
        pop
        previous
        push  (installs patches from quilt series one at a time. quilt push -a installs all patches)
        refresh
        rename
        revert
        series (shows all downloaded patches.)
        setup
        snapshot
        top
        unapplied
        upgrade

Information for developing patches

Getting Authenticated with gitorious.org

Before you can commit to gitorious you need to create an account.

Next, you'll need to create a public/private key pair, and the easiest way to do this is with openssh. If you want to create a pair with windows, there are PuTTYgen/Pageant instructions below under "Alternate Windows Method", but the following may be easier. After you generate a public key you'll share it with gitorious.org; your public key is how gitorious.org authenticates you and checks if have the permissions required to do a commit to a given repository.

ipkg-opt update
ipkg-opt install openssh # *see Note Below
sudo ssh-keygen -t rsa # follow the prompts, ensure you're saving to /var/home/root/.ssh
cat /var/home/root/.ssh/id_rsa.pub  # copy the output and paste it into gitorious key manager

*There's been some work to get dropbear working, but this tutorial assumes you have openssh installed. For information about dropbear and ssh keys, see this page

  • Don't forget to upload your public key from the last statement above to gitorious.org


Next, you'll need to ensure you have your environment properly configured.

echo $GIT_SSH # Should be /opt/bin/openssh-ssh

If the output of this command are anything other than /opt/bin/openssh-ssh, you'll need to update /etc/profile.d/optware. Add

export GIT_SSH=/opt/bin/openssh-ssh

To the top of the /etc/profile.d/optware.

Now you should be able to follow the steps below and contribute your code to gitorious.org.


Alternate Windows Method

The only reasons you might want to pursue this method is if you want to generate a ssh key pair on a Windows box.

Getting your key on window

--Gitorious.org gitorious.org recommends you use msysGit.--

  • On Windows use PuTTYgen to generate a public/private key pair.
Key -> SSH-2 RSA KEY
Key -> Generate key pair

After some wiggling of the mouse your keys will be generated. You should fill in the //Key passphrase// and it's confirmation to secure you key. Save off the public and private key pairs to your user folder.

  • After which you will need to run Pageant on your pc. Pageant holds your private key in memory for PuTTY to use.

Creating a patch

  • Before making any changes to files:
cd / # It is *very* important to be in the / directory when you run quilt.
quilt new patch_name.patch
quilt add /usr/palm/applications/com.palm.app.appYouWantToMod/app/controllers/mod-assistant.js
quilt add /usr/palm/applications/com.palm.app.appYouWantToMod/app/controllers/mod2-assistant.js
  • Now you can make changes on the Pre using vi/nano/joe/whatever, or sftp files to your machine and make changes. Make sure any file you change has been added in the above step.
quilt files # view files that are being tracked
quilt header -e  # add a header to the patch to describe it (please do this!)
  • Once you are finished and ready to create a patch
quilt refresh # this will create/update the /opt/src/patches/patch_name.patch file

Pushing the change back to gitorious.org

  • copy the patch into the modification tree you cloned above
mkdir /opt/src/modifications/application_name # You need to change application_name to the leaf of the palm application id.
cp /opt/src/patches/patch_name.patch /opt/src/modifications/application_name/patch_name.patch
  • Identify yourself in git (use the user you have setup at gitorious.org)
cd /opt/src/modifications
git config --global user.name "user"
git config --global user.email "youremail@example.com"
  • Commit your changes to your local git
git add application_name/patch_name.patch
git commit
  • Since we did a clone the first time, we need to recreate the origin:
git remote rm origin # (if you did a clone, we have to replace the origin)
git remote add origin git@gitorious.org:webos-internals/modifications.git
  • This will destroy your ability to actually pull down updates, so you'll need to modify the /opt/src/modifications/.git/config to contain:
[branch "master"]
        remote = origin
        merge = refs/heads/master
  • Finally, push your changes up to gitorious.org
git push origin master # first time
git push # any future pushes
  • If the push does not work, try to debug the ssh connection
/opt/bin/ssh -v git@gitorious.org

Extended, annotated sample session with quilt

  • First, we just need to setup a file to muck with
root@castle:/# cd /
root@castle:/# echo "Original file" > /usr/test
root@castle:/# echo "2nd lien" >> /usr/test
root@castle:/# echo "3rd ilne" >> /usr/test
root@castle:/# echo "last line" >> /usr/test
  • Start a new patch (normally you'll want to use patch_name.patch, I just wanted a shortened name)
root@castle:/# quilt new p1
Patch /opt/src/patches/p1 is now on top
  • You must quilt add any files that you are going to edit or create before you edit or create them.
root@castle:/# quilt add /usr/test
File /usr/test added to patch /opt/src/patches/p1
  • Just using sed to correct the spelling on the 2nd line
root@castle:/# sed -i -e 's/lien/line/' /usr/test
  • quilt refresh actually finds what you have changed and writes it to the patch file (at this point, you can use git to push your changes)
root@castle:/# quilt refresh
Refreshed patch /opt/src/patches/p1
  • Just for fun, let's do it again
root@castle:/# quilt new p2
Patch /opt/src/patches/p2 is now on top
  • Again, add file, make some changes, refresh to update the patch.
root@castle:/# quilt add /usr/test
File /usr/test added to patch /opt/src/patches/p2
root@castle:/# sed -i -e 's/ilne/line/' /usr/test
root@castle:/# quilt refresh
Refreshed patch /opt/src/patches/p2
  • Just an example of rolling back changes
root@castle:/# quilt pop
Removing patch /opt/src/patches/p2
Restoring usr/test

Now at patch /opt/src/patches/p1
root@castle:/# quilt pop
Removing patch /opt/src/patches/p1
Restoring usr/test

Now at patch /opt/src/patches/enable-browser-downloads.patch
root@castle:/# cat /usr/test
Original file
2nd lien
3rd ilne
last line
  • delete will delete the patch from your series, but leave the actual patch file in /opt/src/patches (so you could import it later)
root@castle:/# quilt delete p1
Removed patch /opt/src/patches/p1
  • Since we removed p1, push will now apply p2. However, since p2 was applied against p1 originally, p2 will report an error. If the changes are too significant, you can force with -f, but you should carefully inspect the resulting files.
root@castle:/# quilt push
Applying patch /opt/src/patches/p2
patching file usr/test
Hunk #1 succeeded at 1 with fuzz 2.

Now at patch /opt/src/patches/p2
  • If we want, we can refresh the patch so that future users of the patch do not receive the "fuzz" warning.
root@castle:/# quilt refresh
Refreshed patch /opt/src/patches/p2
root@castle:/# cat /usr/test
Original file
2nd lien
3rd line
last line
  • cleanup
root@castle:/# rm /usr/test

Background info

Script for Updating/Installing Patches

I just wanted to share the following script that I just finished testing out. It's only been tested on my Pre so far, as I don't have access to any others.. It just updates the patch list, prints out available patches, then lets you choose which to apply.

#!/opt/bin/bash

cd /opt/src/modifications
tput clear
echo Updating list...
git pull
tput clear
cd /

a=0
for inputline in $(find /opt/src/modifications -name *.patch | sort)
do
 a=$(($a+1));
 line="$(echo $inputline)"
 MYARRAY[$a]="$line"
 echo "${a}${line}" | awk -F "/" 'sub(".patch","",$6) {printf "%-3s %-15s %s\n", $1, $5, $6}'
done
echo "q   quit"

x=$(($a+1));
until [ -n "$opt" ] ; do
 read -p "Enter the line number for patch to apply [1 - $a] " opt
 if [ "$opt" = "q" ] ; then
  exit 0
 fi
 if [ "$opt" -lt "$x" 2> /dev/null ] && [ "$opt" -gt 0 2> /dev/null ] ; then
  true
 else
  opt=""
 fi
done

tput clear
cd /
quilt import ${MYARRAY[$opt]}
quilt push
luna-send -n 1 palm://com.palm.applicationManager/rescan {}