pride: INSTALL file and man page

the assumptions

  1. Projects are compatible with Android API 8 and up without version-forks.
  2. Projects have minSDK ver 8, targetSDK ver 17.
  3. Projects are in $PRIDE.
  4. Project Name is in $PRIDE/Name.
  5. If Name has digits, they are at the end of Name (SomeNameNM).
  6. Project Name has a main launcher activity Name in Name.java.
  7. New projects inject the project plate.
  8. Activities have parent activities.
Note that targetSDK is 17 only because that is as far as I can test it at this time. It should work on 18 and up with only minor adjustments of any injections affected by newer APIs.

the dependencies

Note: If your pride lists do not fill the zenity window, the fix for that is here. This bug is an interaction of recent zenity and gtk updates. The fix was published 2013-10-10 but won't be in all distributions for a while.

Note: Cygwin and Cygwin X can be used to create a POSIX environment on a non-POSIX machine. Dependencies can then be compiled. If you are on OS X, you are already on POSIX and only need to download the dependency packages.

the installation

All files unzip to ./pride_install.

  1. cp ./pride_install/pride to ~/.pride
  2. chmod 700 ./pride_install/scripts/*
  3. cp ./pride_install/scripts/* to your $PATH
  4. set all vars in ~/.pride/pride.rc (The defaults work on my machine, not yours.)
  5. link /[wherever]/scripts/pride to desktop
  6. set its icon to ~/.pride/pride.png
  7. fix the path names in ~/.pride/docs.html
Exercise for the Reader: Installing pride's updates requires, at most, a seven-line Bash script, including the bang line, for unzipping the download, installation and clean-up. Script should preserve pride.rc, name, and package in $dot. (Subtext: Stop whining.)

the boilerplate

The files in .pride/plate/project make it possible for pride to work with everyone's projects and for everyone to have their own plate as well. Pride assumes injection of .pride/plate/project. Pride::Injection only works if the new project script injects the distribution's plate. Any changes to the project plate baseline will be announced at the top of the page. This means that you need your own personal boilerplate directory for all changes and additions to the pride plate.

So customize pr_personalPlate.sh for injecting your additions and changes. This script is run from a zenity dialog box after project creation if PERSONAL is defined in pride.rc.

the style

Pride's default style is the style used for newer apps by Poor Richard's Alchemy. In other words, it's my style. You can use it if you like it. But you can easily change the color by going to the android holo colors site to get your widgets generated. You just pick a color, check off all the widget bits (except Tabs which require Android 11+), and download their zipfile. Put that res/ tree in your PERSONAL directory from the pride.rc file. Then customize pr_personalPlate.sh for its injection. This script is run from a zenity dialog box after project creation if PERSONAL is defined in pride.rc. You will need to use EdgeEffectOverride injection to change the edge flare of any List to a color more appropriate than Android's Halloween Green or Emergency Exit Blue. All Pride List injections already use this class. You can get even more style elements generated here.

Note that Pride has the resources for the number picker and switch backports which are linked from the android-holo-colors site. These have NOT been implemented as injections. Their zip files are in ~/.pride/hold and their image bits are already in the project plate. Maybe you can get them into an injection before I do. These would make nice contribs, ne?

Note that Pride's handling of styles is a work-in-progress. At this time, you must explicitly declare the pra_* styles for each element in your layout XML files (i.e., style="?editText"). I am looking to simplify this as well as for the best way to handle multiple styles. See RoadMap

the libs and their docs

Pride includes the ftp4j and commons-io jar files in ~/.pride/plate/libs. These are documented in ~/.pride/docs and these docs are linked into ~/.pride/docs.html. You will need to fix the paths to these docs in that HTML file. Some of the default Android injections use the android-support-v4.jar. You must obtain this from the Android downloads and then put it in ~/.pride/plate/libs.

the tools

Pride::Help

Displays project information and points you to this page.

Pride::Projects

Select

Sets the current project for the pride system. Changed here or by creating a new project. Note that the Batch* scripts set the current project to the last project in the batch run.

New

Creates a project with `android` and injects boiler-plate from ~/.pride/plate/project and gives the option of running pr_personalPlate.sh. Sets current project. Leaving the domain field blank makes pride.rc's DOMAIN the domain. All new elements come buildable and runnable with pride's baseline plate injection. For the injections to work, you must inject the project plate. The personal plate injection is for injecting your own styles and other files. Customize pr_personalPlate.sh for this injection. Your $PERSONAL plate directory is set in pride.rc

Backup

Uses zenity to select a project "Name" then calls "backupProject.sh Name". You must create your own backupProject.sh script.

Hidden

Hides and unhides multiple project directories in the workspace. This is done by simply flopping $PRIDE/$name to $PRIDE/.$name and back.

Import

Imports an eclipse project from $IMPORTS (usually ~/workspace). This will duplicate the eclipse-based project in $PRIDE. Your main launcher activity must be com.example.name.Name.java to work with pride. You need to make any namespace changes to your app correctly or you will break it in Android - Google Play namespace.

After you import a project, you will still need elements of the project plate so that the injections will work. These will all be res elements in .pride/plate/project/res, either entire files or entries from files in res/values. Compilation errors will show you what you need. These files can be loaded into your PERSONAL plate directory so that they are injected on import.

Icons

You create your 512x512 icon with alpha layer in an image editor and save it as $PRIDE/$name/ic_launcher-web.png. Then run this Icons command on that project and ImageMagick will generate the files.

UpdateClass

This is for updating a class which is used in multiple projects. You select the project with the newest version and then select that class file in that project. The script then updates all such classes in all projects and correctly sets their package name at the top of the file. You can use this in package subdirectories. Appends changes to ~/pr_updated.txt. Note that when this script changes name1 to name2 it can affect name1 if it appears anywhere in the file. This occurs in one of my files which invokes my other apps by Intent.

UpdateResDir

This is for updating any number of files from one of the $PRIDE/$SOURCE/res/ to any number of selected $PRIDE/$DEST projects.

UpdateSeries

This is for updating a main class which is used in multiple projects. The class name must be a name (epub, SomeName) followed by a two-digit series indicator at the end (SomeName01). Indicator must be numeric. Example from my apps: I have updated epub04.java with a bugfix. I choose UpdateSeries, then project epub04, then I enter "epub" (without the quotes) in the Prefix dialog. This then updates epubs 01 through 11. Then I BatchBuild, BatchLoad, test the fix, and BatchRelease. Only use this on the main app Java file. Appends changes to ~/pr_updated.txt.

ScreenShot

Executes ddms from Android's tools. Select not the device, but the thread below the device. Then select screenshot in app menu. Hit save and then done. Viewing the picture before hitting "done" will have unpredictable results from desktop image viewers. Note that ddms is a debugger, if you use that sort of thing.

BatchBuild

Cleans and builds multiple projects sequentially. This is useful for users who have several apps on one codebase. Resets current project to last project built.

BatchLoad

This loads multiple apps on all devices. It is like Pride::Run but without any terminals running logcat. After I BatchBuild, I use this to install all apps on my devices so that they are up-to-date. My apps which share codebases differ only by switches. So I test the first one, BatchBuild, BatchLoad, check the switches, and then BatchRelease. This does not reset the current project.

BatchClean

Runs `ant clean` in selected project directories.

BatchRelease

Releases multiple projects sequentially. Expect a pregnant pause while the release script runs `ant clean` and then the normal Pride::Release terminal will pop up. Resets current project to last project built.

Draw9Patch

Executes draw9patch from Android's tools for creating scaleable graphics.

Clone

Clones any existing un-hidden project into a new app and properly sets the namespace.

SDK Manager

This runs "android sdk" to bring up the Android updater and installer that comes with the Android tools.

Pride::Snapshot

The two normal options back up and restore the current project using directory $SNAPSHOT defined by you in pride.rc. There is a safety on restore to prevent disasters. Version snapshots create persistent fall-backs which are not overwritten by succeeding normal snapshots. There is also an option used for deleting stale snapshots.

Pride::Injection

Used to inject new elements into projects. You must inject the new project plate for these to build and run. Pride injections are in a ready-to-run state for projects but they will usually need to be wired into the existing code.

Pride::Imports

This acts upon the MOST RECENTLY SAVED file in $name/src/[pkg]/. Place a "#" in front of any number of Java objects like "#Button" or "#AlertDialog.Builder". You can have more than one on a line. Hit Pride::Imports. Refresh the file. Imports are inserted just before the main class declaration after existing imports.

Pride::Clean

This first runs pr_header.sh and remove_unused_imports.awk on the project source files. Then it runs `ant clean`. No other command, except BatchBuild and BuildClean, includes "clean". You will NEED to use clean when you change layouts or other XML resources. Even deleting one line in an XML throws the build off. Use clean any time you change these things. Clean alters (or at least touches) all source files. Close your files in the editor before running clean.

Pride::BuildClean

Runs Pride::Clean and then Pride::Build. This is useful when you are working with XML files and building GUIs.

Pride::Build

Runs `ant debug` in a spawned shell and leaves "pr_build.log" in the current project root.

Pride::BuildRun

Runs Pride::Build and then Pride::Run. This is useful when you are making minor adjustments and want to quickly see the results.

Pride::Run

Loads the current project onto all connected devices with adb and starts its main activity. It does NOT rebuild the debug apk. Uses `rxvt` to display logcat. Change term to suit yourself. Set your logcat watch flags in the script. See the logcat docs.

Pride::Uninstall

Removes current project from all devices with the option each time to keep or remove the app's data.

Pride::Release

First, this optionally strips project of unused images with pr_stripImgs.sh which runs `lint --check UnusedResources` to generate a list of unused PNG files and then deletes those files from the project's res directories. Lint requires that the project be built and have class files present for the analysis to work properly. (For safety's sake, this snapshots $PRIDE/$name to $SNAPSHOT/$name.rel_`date +%s` before removing unused resources.)

Then it uses $RELEASE_KEY* in pride.rc to create a signed, ready for upload-to-market APK. Renames apk to $NAME.apk and moves it to RELEASES dir.

If BACKUPONRELEASE is defined, runs `backupProject.sh $name`. If VERSIONONRELEASE is defined, runs `version$name.sh`. You can create a single version-release script for multiple projects with names in the form of SomeNameXX where X is a digit called `versionSomeName.sh` This script is called with the SomeNameXX as its $1, i.e. `versionSomeName.sh SomeName01`

Pride::JNIClean

Runs `ndk-build clean` in $PRIDE/$name

Pride::JNIBuild

Runs `ndk-build all` in $PRIDE/$name within a spawned shell.

Pride::PersonalPlate

Runs `pr_personalPlate.sh` on the current project to overwrite old style or other xml elements with new ones and to add any personal boilerplate code used in all your projects. There is a safety switch on this to prevent accidents.

Pride::Lint

Runs `lint -Wall` to generate an HTML report and loads that report into $BROWSER.