Packaging Homebrew Apps for Stock Pre without Rooting

How To Create Packages for Installation on a Stock Pre

Brought to you by...

• xorg - started the initiative, host of this page
• simplyflipflops - discovered the install via email link (no longer works with OS 1.0.4)
• Shaya Potter - provided details for creating signatures

Summary

There are three main components to creating/installing homebrew application packages:

1) Packaging the application for Debian ipkg

2) Generating a signature for the package

3) Installing using the PreBrew method. (replaced the email link method)

and an extra important 4th... 4) Testing... Please test your code well and be responsible. Others will help you succeed and develop quality apps in this Pre Central forum thread. Please post your tests in that thread with a beta disclaimer before releasing to the public.

This guide does not show how to build new applications, just how to package your existing application for distribution on a stock Pre. Here is a guide for creating your own WebOS applications.

Packaging Instructions (xorg method)

This section is geared towards those already experienced with Linux/Unix and Debian packaging. Some commands may require slight modifications depending on platform you package on. See other methods below.

How to create a signed package for public distribution on a stock Pre. This assumes you already have your application functioning on a rooted Pre in god mode. Your app should be located in /var/usr/palm/applications/yourappfolder.

Only distribute __your__ code Be careful to follow copyright laws and not include code that isn't yours unless you have permission. If you include open source code, follow those rules. Publicly distributing mods of stock Pre applications is not recommended.

Dependencies You'll need openssl, possibly full gnutar and a full featured ar command to //create// archives. I'm not going to explain how to get these in the //experienced// section. If you package on a full Linux box with development tools, this should not be an issue. If packaging within a rooted Pre, you'll need to install the arm-based version of these programs (hint: /opt/bin/ipkg-opt install openssl, binutils, tar). Post in this Pre Central forum thread if you need more help finding/installing these.

Download this sample package into a blank project directory

wget http://bit.ly/10ROa8 -O sample.ipk

Extract sample and build the core files Extract the contents, this is how your bundle should look...

ar -x sample.ipk

Extract the contents of control.tar.gz. You'll need to change the control file to fit your app and tarball it back.

tar xzvf control.tar.gz
vi control  

(edit the structure to fit your app, the "package" must match the "id" in your appinfo.json file.)

tar czvf control.tar.gz ./control ./rules

Note the structure of data.tar.gz, which contains the /usr/palm/applications (the actual program). Note that it has an absolute leading /

tar tzvf data.tar.gz

tarball your entire app directory into data.tar.gz with the P flag to get absolute paths with a leading /. Not all distros have P flag in tar. You may need to get/use gnutar.

tar cvPzf  data.tar.gz /usr/palm/applications/(your application folder)

confirm that you have a leading slash (/usr/.... not ./usr/...)

tar tzvf data.tar.gz

How to sign a package (thanks to Shaya Potter) create a private key (depending on platform, this command may ask for location data, just hit enter through each. ignore the error this command may generate. if you get a mycert.pem greater than 0 bytes, it probably worked. you'll find out in the sig validation test.)

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem

extract the public key

openssl rsa -in mycert.pem -pubout -out pubkey.pem

sign your ipk

cat control.tar.gz data.tar.gz debian-binary | openssl dgst -sha1 -sign mycert.pem -out signature.sha1

validate the signature

cat control.tar.gz data.tar.gz debian-binary | openssl dgst -sha1 -verify pubkey.pem -signature signature.sha1

Verified OK

Package it up package it up with ar

ar -r (yourpackagename).ipk control.tar.gz data.tar.gz debian-binary pubkey.pem signature.sha1

confirm your .ipk package looks ok...

ar -t (yourpackagename).ipk

(yourpackagename, obviously, should be unique and does not need to start with "com.": The general idea is to use the "reverse domain name" notation like the one commonly used by the java package names. this allows globally unique names without the need of a central "Creator Registry" like the one used in Classic PalmOS)

Install (PreBrew method) The email link method no longer works on OS1.0.4 or newer. Here is the latest PreBrewmethod.

Test Deletion It is important you test that the application can be deleted on a stock Pre (non-rooted) before releasing to the public. Make sure the package name in the 'control' file matches the id name in the json file. Check the json file , refer to json entries in The HowTo Guide.

Test, Test and ReTest Test your application well before releasing to the public. Send it to friends first before releasing or post on Pre Central forum thread for others to test as a pre-release. Don't rush releasing. You may tarnish the homebrew community if it is flooded with poorly written untested apps. Be responsible and consider following the upcoming recommended best practices. I'll be posting more about Best Practices later.

Variations of Commands

List variations of commands that may need to be tried depending on distribution.

Is tar P flag and data file path with leading / required? We've debated this. Some say it's needed others say it's not. Since original stock Pre packages use a leading /, I also structured it that way.

tar - you may need a tar command that has -P flag. If you have gnutar, it may be located in /opt/bin/gnutar depending on your distro. Change all tar commands with gnutar.

tar vs ar - can you just use tar instead of ar in final packaging? When I look at an original stock app ipkg, I can only open it with ar, so it would seem using ar is needed. Others say they have just used tar but probably safest to use ar.

openssl - some versions ask for location info - just hit enter through each. Other versions may give an error that it can't find the location file - just ignore it as long as it generated a mycert.perm greater than zero bytes.

Homebrew Repository

Pre Central has started a homebrew repository to post your completed app. You can create a thread dedicated to your app. You need to have a fully functioning app before you are allowed to create your own thread.

Packaging Services

If you have an application and are say, a strong web developer but not strong in linux or packaging, you could ask someone to package your app for you. Ask someone in this Pre Central thread if they would be willing to package your app for you. With scripts, it only takes a few nanoseconds if the app directory is supplied.

simplyflipflops is looking into a web service to automate generating the package. See page 14 of the thread above.

Packaging Script (quailish method)

Packaging script from quailish with more specific tar methods. Use this after you've made all of the file mods needed.

package.sh

#!/bin/sh
tar -czv -f control.tar.gz ./control ./rules
tar -cPv --no-recursion -f data.tar / /usr /usr/palm /usr/palm/applications
tar -rPv --recursion -f data.tar /usr/palm/applications/com.myappname
gzip --best data.tar
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
openssl rsa -in mycert.pem -pubout -out pubkey.pem
cat control.tar.gz data.tar.gz debian-binary | openssl dgst -sha1 -sign mycert.pem -out signature.sha1
cat control.tar.gz data.tar.gz debian-binary | openssl dgst -sha1 -verify pubkey.pem -signature signature.sha1
ar -r (yourpackagename).ipk control.tar.gz data.tar.gz debian-binary pubkey.pem signature.sha1
ar -t (yourpackagename).ipk 

Makefile (dsevil's method)

This approach is suited for those who develop WebOS applications on their laptop or desktop computer.

It does not (yet) support applications that contain files outside the root application directory.

- run: wget -O Makefile http://webonastick.com/webos/Makefile.txt

- Edit the top section.

- Make sure your package files are in the directory named by TARGET in the Makefile.

- Run "make package" or just "make" to generate your package.

NOTES:

- Not guaranteed to work unless you have GNU tar, make, ar, du, and possible other utilities installed.

- The usual general-lack-of-warranty disclaimer applies.

- Requires installation of OpenSSL command-line utilities.

- You don't edit appinfo.json; you edit Makefile; running 'make' generates it for you.

Original post: on Pre Central

Another Approach (pimpmypre method)

Method to create an ipk by using a Linux hosted web server.

You will need SSH access to your server - ask your provider and they will give it to you.

Create 3 folders (to make it easy).

Control
Data
Package

Put your control files in the control folder.

Put usr/palm/applications/(your app) folders in the data folder.

In the data folder, type:

tar cvPzf data.tar.gz .

//(xorg note: some think data path above needs a leading / but pmp said this works for him. keep in mind that stock Pre apps use an absolute path using leading /, not this relative path method. see command variation section above.)//

Move the tarball to the package folder.

cd to the control folder
tar cvPzf control.tar.gz .

move this tarball to the package folder

cd to the package folder
echo "2.0" > debian-binary
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
--(enter through the fields)

openssl rsa -in mycert.pem -pubout -out pubkey.pem
cat control.tar.gz data.tar.gz debian-binary | openssl dgst -sha1 -sign mycert.pem -out signature.sha1

ar -crf (package name).ipk debian-binary data.tar.gz control.tar.gz mycert.pem pubkey.pem signature.sha1 

Cygwin Approach (Packaging in Windows)

How to package in Windows...

First download Cygwin here, then simply click next till you get to a screen called "Select Packages". In the top right click the "View" button. The list is in alphabetical order and you will have to enable 2 items by clicking the "skip" text. The first one is "binutils - The GNU assembler, linker and binary utilities. The second one is "openssl: The OpenSSL runtime environment".

With these setup you can now do the commands described above.

If anyone has successfully packaged and tested this method, please comment here that this method works. I had issues with it.

Hmm... I wrote it so I would hope it works.

Update: I followed the xorg method on windows with cygwin and it worked. - d0lph1nk1ng

Another Approach (yourname method)

If you have another packaging method, such as packaging scripts and got it working, please post it here - or a link to your scripts. Create an "Another Approach" tag for each new method. You may credit yourself in this section and add yourself as a contributor at the bottom of this page.

Disclaimer

Our intent is to help the Pre/webOS development world release applications. We do not support or encourage using this information for malware. We completely oppose misuse.

We are white hat developers (friendly to the community and wide open with approach), not black hat hackers. The intent is to provide direly needed momentum for the development community and for Palm. If Palm wants to shut down this initiative, I will comply. Palm can contact me at Pre Central as xorg.

Discuss

See discussion and how this unfolded on Pre Central. Is a good read for those would like to see how white hat hackers sleuth.

BTW, we made the Pre Central headlines. And Engadget.

Original Credits

The team...

• xorg - started the initiative
• simplyflipflops - discovered the install via email link
• Shaya Potter - provided details for creating signatures

Please consider crediting the three of us somewhere in your applications. Thanks.

Contributors

If you have contributed another method or usable information, please credit yourself here.

qualish - submitted another packaging method with script

dsevil - submitted Makefile packaging method

Discuss Ideas Here

Yo yo yo, xorg here. I've been trying to figure out a way to install a homegrown app on a Pre that has not been rooted (while we wait for the SDK to be released). I've been searching the the app installer code to see if there is another way to load other than through the App Catalog.

Ideas...

• I was hoping to find something that checks a folder on /media/internal but haven't found anything.
• If we can figure out how the app is packaged (tarballed, ipkg or whatever) from the App Catalog, maybe there is a resource tag to autolaunch the installer when opening. This might allow sending the packaged app via email and opening from there.
• Update: Looks like apps are packaged with ipkg. We need to find a way to launch ipkg on the homebrew pkg bundle without rooting the phone.

Would like to brainstorm with others. There are no bad ideas. Throw out anything on where to look.

Places To Investigate

grep through subdirectories...

/usr/palm/applications/com.palm.app.findapps

Launch apps based on extension. Can we trick one of these to open a packaged app?

/usr/palm/command-resource-handlers.json

Put youse thinking caps on and throw out any ideas. Update here and/or on Pre Central.

Let's beat the SDK to the punch! The challenge is to find a way to install an app with permission of user but without making root changes. Make it so.

Progress

Update 6.20 afternoon: simplyflipflops (sff) has successfully installed an existing app by emailing himself a link to a Debian package and opening from email (something I suspected would be possible through email, which prompted me to start this initiative - sff found how). It won't work from the Pre browser, you must email the link to yourself and open from Pre email. Again, this will not work directly from the Pre web browser.

Several have confirmed this works on a non-rooted Pre.

The next question is... Does this require a signed package?

Update 6.21 morning

sff and I have made a lot of progress on figuring out the packaging. sff tried a homebrew app but is running into possibly signature issues. xorg is attempting to bypass signatures altogether.

Update: 6.21 afternoon

We've got packaging down pat and have moved on to signatures/keys. I repackaged a stock app with the stock keys/sigs and it works. Taking the key/sigs out is a no go, although a checksum itself might be the issue alone.

I was able to confirm that the package does not require a palm.com address to install. I was able to download and install a stock app installed on another web server.

We've confirmed signatures are required. Shaya Potter has been helping out with signatures. That's the major open item.

SUCCESS!!!!!

Update: 6.21 3:45pm cst

We got it working thanks to Shaya Potter's knowledge of signatures and packaging. He doesn't have a Pre but walked us through how to do sigs. Pre Central has agreed to host the sample program.

A sample mailto link can be found at Pre Central article on the success . Note that after receiving the email and clicking the link, nothing appears to happen. However, if you bring up the launcher and scroll to the bottom of the first page, a new icon will be there.