Difference between revisions of "Applying Patches"
m (quilt push -a) |
m (minor alternation of wording and grammer in intro and made it a heading) |
||
Line 1: | Line 1: | ||
− | + | ==Introduction== | |
− | Since these patches will come from many different places, and will need to be removed before each OTA update and then reapplied | + | We cannot legally redistribute Palm source code (it is copyrighted code, and is not released under an open source license) therefor 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. |
− | + | ==Setup Procedure== | |
− | + | (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). | |
− | = Setup Procedure= | ||
− | (Note: Even though you installed the optware quilt patch manager, it won't damage anything to follow | ||
* Log into your Pre, and gain root privileges. | * Log into your Pre, and gain root privileges. | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
sudo -i # Yes, the -i is important. | sudo -i # Yes, the -i is important. | ||
</nowiki></pre> | </nowiki></pre> | ||
+ | |||
* Put your Pre in to Read Write Mode | * Put your Pre in to Read Write Mode | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
mount -o remount,rw / | mount -o remount,rw / | ||
Line 32: | Line 29: | ||
* Create a directory in which 'quilt' will manage your chosen modifications: | * Create a directory in which 'quilt' will manage your chosen modifications: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
mkdir -p /opt/src/patches | mkdir -p /opt/src/patches | ||
Line 38: | Line 34: | ||
* Edit /opt/etc/quilt.quiltrc to point quilt to that directory: | * Edit /opt/etc/quilt.quiltrc to point quilt to that directory: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
sed -ire 's|^[\s#]*QUILT_PATCHES=.*|QUILT_PATCHES=/opt/src/patches|' /opt/etc/quilt.quiltrc | sed -ire 's|^[\s#]*QUILT_PATCHES=.*|QUILT_PATCHES=/opt/src/patches|' /opt/etc/quilt.quiltrc | ||
Line 44: | Line 39: | ||
* Clone the webos-internals modifications repository: | * Clone the webos-internals modifications repository: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
cd /opt/src | cd /opt/src | ||
Line 50: | Line 44: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | = Importing and Applying Patches= | + | ==Importing and Applying Patches== |
* Ensure your list of modifications is up to date | * Ensure your list of modifications is up to date | ||
Line 57: | Line 51: | ||
git pull | git pull | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
** 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 | ** 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 | ||
<pre><nowiki> | <pre><nowiki> | ||
Line 71: | Line 64: | ||
* Browse the set of available patches. Each patch should have a description at the top. | * Browse the set of available patches. Each patch should have a description at the top. | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
find /opt/src/modifications -name *.patch | find /opt/src/modifications -name *.patch | ||
Line 77: | Line 69: | ||
* Choose a patch from the modifications repository and import it into your own patches directory: | * Choose a patch from the modifications repository and import it into your own patches directory: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
cd / # It is *very* important to be in the / directory when you run quilt. | cd / # It is *very* important to be in the / directory when you run quilt. | ||
Line 84: | Line 75: | ||
* Verify that quilt has imported the patch successfully: | * Verify that quilt has imported the patch successfully: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
# You should still be in the / directory to run quilt. | # You should still be in the / directory to run quilt. | ||
Line 91: | Line 81: | ||
* Instruct quilt to apply your patch | * Instruct quilt to apply your patch | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
# You should still be in the / directory to run quilt. | # You should still be in the / directory to run quilt. | ||
Line 114: | Line 103: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | = Removing all patches= | + | ==Removing all patches== |
Before you accept an OTA update, you should remove any patches you have applied. Luckily, using quilt makes this very easy. | Before you accept an OTA update, you should remove any patches you have applied. Luckily, using quilt makes this very easy. | ||
* Remove all patches: | * Remove all patches: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
cd / # It is *very* important to be in the / directory when you run quilt. | cd / # It is *very* important to be in the / directory when you run quilt. | ||
Line 125: | Line 113: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | = Reapplying all patches= | + | ==Reapplying all patches== |
− | After your OTA update is complete, you will want to reapply any patches you have selected. | + | 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: | * Apply all patches: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
cd / # It is *very* important to be in the / directory when you run quilt. | cd / # It is *very* important to be in the / directory when you run quilt. | ||
Line 137: | Line 124: | ||
* Put your Pre back in to Read Only mode | * Put your Pre back in to Read Only mode | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
mount -o remount,ro / | mount -o remount,ro / | ||
</nowiki></pre> | </nowiki></pre> | ||
− | = Information for developing patches= | + | ==Information for developing patches== |
− | == Getting Authenticated with gitorious.org== | + | ===Getting Authenticated with gitorious.org=== |
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]. | ||
Line 181: | Line 167: | ||
* 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. | * 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=== |
* Before making any changes to files: | * Before making any changes to files: | ||
Line 205: | Line 191: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | == Pushing the change back to gitorious.org== | + | ===Pushing the change back to gitorious.org=== |
* copy the patch into the modification tree you cloned above | * copy the patch into the modification tree you cloned above | ||
Line 248: | Line 234: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | = Extended, annotated sample session with quilt= | + | ==Extended, annotated sample session with quilt== |
* First, we just need to setup a file to muck with | * First, we just need to setup a file to muck with | ||
<pre><nowiki> | <pre><nowiki> | ||
Line 336: | Line 322: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | = Background info= | + | ==Background info== |
* [http://pkg-perl.alioth.debian.org/howto/quilt.html quilt] | * [http://pkg-perl.alioth.debian.org/howto/quilt.html quilt] | ||
− | = Script for Updating/Installing Patches= | + | ==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. | 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. |
Revision as of 20:27, 26 July 2009
Introduction
We cannot legally redistribute Palm source code (it is copyrighted code, and is not released under an open source license) therefor 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.
Setup Procedure
(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.
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 packages, 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 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
- 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
Removing all patches
Before you accept an 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 /
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 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.
Getting your key on windows
- Download [*http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTYgen] and [*http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Pageant]
--Gitorious.org gitorious.org recommends you use msysGit.--
- On Windows use [*http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html 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.
- To commit changes to gitorious.org from the pre you will need to install openssh on the device.
ipkg-opt update ipkg-opt install openssh # since dropbear doesn't do agent forwarding, you need to use openssh
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
sudo ssh-keygen -t rsa # follow the prompts cat ~/.ssh/id_rsa.pub # display the public key you need to paste into gitorious
- 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
- 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
- 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.
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 {}