User Tools

Site Tools


mozilla-devel:building_the_staff_client

User Comments

Old Alpha release instructions

Instructions for 2.0, 1.6 and earlier

Building the staff client

The staff client is built as part of the “make install” process in a normal load. One can also build one by going to the Open-ILS/xul/staff_client directory and typing “make build”. There are a number of options that can be specified, either during “make install” or “make build”.

BUILD_ID

The staff client has a BUILD_ID variable that is, by default, a date/time string. There is no reason to force this normally, but should you want to you can add it in after “make”. For example:

During install:

make STAFF_CLIENT_BUILD_ID=my_test_id install

From staff_client directory:

make STAFF_CLIENT_BUILD_ID=my_test_id build

VERSION

The staff client's version is normally pulled from the README file in the source root. If building from trunk the version is 0trunk.revision, where revision is either a revision automatically pulled from SVN or an empty string on failure. If you plan on making extensions update automatically your version needs to conform to the Toolkit Version Format and newer versions need to be “higher” than older versions according to it.

One can override the version similarly to the BUILD_ID:

During install:

make STAFF_CLIENT_VERSION=0mytest.200 install

From staff_client directory:

make STAFF_CLIENT_VERSION=0mytest.200 build

STAMP_ID

The staff client's “STAMP_ID” is actually the URL piece on the server and should be used when copying the build/server directory to the web/xul folder. By default it is built off of the version, but can be specified manually. You may also want to have multiple “versions” of the staff client with different stamps, possibly for different uses or client-side customizations.

As with the BUILD_ID and version you can override it:

During install:

make STAFF_CLIENT_STAMP_ID=my_test_stamp install

From staff_client directory:

make STAFF_CLIENT_STAMP_ID=my_test_stamp build

A note, it is not considered a good idea, but a “versionless” staff client can be made by specifying an empty stamp, but this should NOT be done during install:

From staff_client directory:

make STAFF_CLIENT_STAMP_ID='' build

This replaces older STAFF_CLIENT_BUILD_ID='' instructions for creating such a client.

Branding Options

Mainly for when you are making installers, windows installers in particular right now, you can set up branding for beta or release builds of Evergreen. This will change icons/images for the client shortcut icons and the installer.

This is done with the “rigbeta” and “rigrelease” targets.

From staff_client directory (only run one):

make rigbeta
make rigrelease

After running one or the other you should also build or rebuild the staff client so that the icon branding takes effect. You can also do this before the “make install” step, if you want.

Advanced build options

In addition to the basic options above there are a number of other options for building the staff client, pretty much all are make targets and thus require you to be building from the staff_client folder.

Rebuild

If run alone, or placed BEFORE any of the below options the staff client will be “rebuilt” with the same version and stamp id as the previous build. This is useful for testing changes during development or adding things like permachine to a build from install time.

From the staff_client directory:

make rebuild

Initial Hostname

To set an initial staff client hostname.

During making the staff client:

make INITIAL_HOST=hostname build

During Evergreen configure:

./configure --with-initialhost=hostname

Developer Build

A Developer Build of the staff client can be created by substituting “devbuild” for “build” when running make from the staff_client directory. This build will contain an extra configuration file that enables some developer options.

From the staff_client directory:

make devbuild

Per-machine Registration Build

A configuration variant for per-machine (instead of per-user) workstation registration and offline transaction storage can be built by replacing “build” with “permachine”. This build will contain an extra configuration file to enable that functionality. This is compatible with using “devbuild” and order does not matter between them.

From the staff_client directory:

make permachine

Compressed Javascript

If you replace “build” with “compress-javascript” then Google's Closure Compiler will be run on the staff client after the build process.

From the staff_client directory:

make compress-javascript

If you want to combine a developer build with this you can tack them together, order is important:

From the staff_client directory:

make devbuild compress-javascript

Automatic Update Host

The host used for automatic update checking can be set or overridden with the AUTOUPDATE_HOST option:

During install:

make AUTOUPDATE_HOST=localhost install

From staff_client directory:

make AUTOUPDATE_HOST=localhost build

For more information see the staff client automatic update documentation.

Installing/Activating the staff client

The staff client built at the “make install” stage is automatically installed and activated for use. If you are making one from the staff_client directory, however, you need to take additional steps.

Assuming your installation is in /openils and you have already built the staff client, from the staff_client directory run:

mkdir -p "/openils/var/web/xul/$(cat build/STAMP_ID)"
cp -R build/server "/openils/var/web/xul/$(cat build/STAMP_ID)"

Packaging the staff client

Once the staff client is built you can build several forms of client packages with make commands from the staff_client folder.

Generic Client

Making a generic client requires that you have the “zip” utility installed in your system, and will produce an xpi file that is suitable for use with the –install-app parameter of xulrunner.

The output file “evergreen_staff_client.xpi” will be created.

make generic-client

Windows Client

Making a windows client requires that you have the “unzip” and “makensis” utilities installed in your system. The “makensis” utility may be installed with a “nsis” package, although you will need a recent version for all functionality to be available. Version 2.45 or later of makensis is recommended.

As a side note, if you wish for the staff client to have a link icon/tray icon by default you may wish to provide a pre-modified xulrunner-stub.exe. Place it in the staff_client directory and the makefile will use it instead of the one that comes with the downloaded xulrunner release.

If you wish to do so the version of xulrunner-stub.exe need not match exactly. You can use a tool like Resource Hacker to embed icons.

Useful icon ID strings:

IDI_APPICON - Tray icon
32512 - Default window icon

The output file “evergreen_staff_client_setup.exe” will be created.

make win-client

Linux Client

The linux client is merely a tar.bz2 file with xulrunner bundled with it.

If you build the 32-bit version, the output file “evergreen_staff_client_i686.tar.bz2” will be created, for 64-bit version the output is “evergreen_staff_client_x86_64.tar.bz2”

make linux32-client
make linux64-client

Extension

The staff client can optionally be built as a Firefox extension. Doing so requires the “zip” utility be installed.

The output file “evergreen.xpi” will be created.

make extension

Staff Client Automatic Updates

The staff client can be rigged to automatically update. In addition to the below you may wish to read Deploying Automatic Updates.

WARNINGS

Automatic update server certificate requirements are more strict than normal server requirements. XULRunner and Firefox will both ignore any automatic update server that is not validated by a trusted certificate authority. Servers with exceptions added to make the staff client accept them WILL NOT WORK.

In addition, extension updates REQUIRE one of two things to be done for the update.rdf file. It must either be served from an SSL server, or it must be signed with the McCoy tool. You can pre-install the signing key into the install.rdf file directly, or install it into a copy as install.mccoy.rdf. If the latter exists it will be copied into the build instead of the original install.rdf.

Autoupdate Host

The automatic update host can be provided in two ways. The first is at configure time:

./configure --with-updateshost=hostname

Don't forget to include your other configure options.

The other is during the staff client build process with AUTOUPDATE_HOST=hostname (see above).

If you specify just a hostname (such as example.com) then the url will be a https url (such as https://example.com). If you wish to use a non-https url then prefix the hostname with http:// (such as http://example.com).

If neither option is used then the staff client won't include the automatic update preferences by default.

Building updates

Similar to building clients, the generic-updates, win-updates, linux-updates, and extension-updates targets will build the update files for the staff client. If you plan on building them all you can just use the “updates” target.

A “full” update will be built for each specified target (or for all if just “updates” is used). For all but extensions any previous “full” updates (archived in /openils/var/updates/archives by default) will be used to make “partial” updates. Partial updates tend to be much smaller and will thus download more quickly, but if something goes wrong with a partial update the full update will be used as a fallback. Extensions do not appear to support partial updates at this time.

make updates
make generic-updates
make win-updates
make linux-updates
make extension-updates

Building updates with clients

To save time/effort you can build updates and manual download clients at the same time by adding -client to the target, such as win-updates-client. This does not work for extension-updates, but does work for the “build all” updates target.

The clients will be installed alongside the updates and listed on the manualupdate.html page, rather than left in the staff_client directory.

make updates-client
make generic-updates-client
make win-updates-client
make linux-updates-client

Activating the update server

The apache example configuration creates an “updates” folder that, by default, points at /openils/var/updates/pub. This folder contains several script files that pretend to be normal files and/or folders, as well as one HTML file.

The following scripts should be marked as executable:

check, download, manualupdate.html, update.rdf

The updatedetails.html file is the fallback page for the update details.

The check script is used for xulrunner updates, the update.rdf script for extension updates.

The manualupdate.html script checks for clients to provide download links when automatic updates have failed and uses the download script to force a download of the generic client xpi (compared to Firefox trying to install it as an extension).

Other tips

Multiple workstations on one install

Multiple workstation registrations for the same server can be accomplished with a single staff client install by using multiple profiles. When running xulrunner you can specify -profilemanager or -P (ensure that P is uppercase on Linux!) as an option to force the profile manager to come up. Unchecking the “Don't ask at startup” option will make this the default.

Once you have opened the profile manager you can create additional profiles, one for each workstation you want to register. You may need to install SSL exceptions for each profile.

When building win-client, win-updates-client, or updates-client, specifying “NSIS_EXTRAOPTS=-DPROFILES” will add an “Evergreen Staff Client Profile Manager” option to the start menu.

make NSIS_EXTRAOPTS=-DPROFILES win-client

Multiple staff clients

It may get confusing if you aren't careful, but you can log in to multiple evergreen servers at the same time, or a single evergreen server multiple times. In either case you will need to create an additional profile for each additional server or workstation you want to log in as (see previous tip).

Once you have done so, run xulrunner with the -no-remote command line option (in addition to -profilemanger or -P if needed). Instead of xulrunner opening a new login window on your existing session it will start a new session instead, which can then be logged in to a different server or workstation ID.

Building a Macintosh Staff Client

  1. An app file is basically a folder. Start with a folder stucture like this:
  • Evergreen.app
    • Contents
      • Frameworks
      • Resources
      • MacOS

eg:

  mkdir -p Evergreen.app/Contents/Frameworks
  mkdir -p Evergreen.app/Contents/Resources
  mkdir -p Evergreen.app/Contents/MacOS
  1. Create a new file in Evergreen.app/Contents/Info.plist with the following (adjust for your version of Evergreen)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>CFBundleExecutable</key>
        <string>xulrunner</string>
        <key>CFBundleGetInfoString</key>
        <string>OpenILS open_ils_staff_client rel_2_4_0</string>
        <key>CFBundleInfoDictionaryVersion</key>
        <string>6.0</string>
        <key>CFBundleName</key>
        <string>Evergreen Staff Client</string>
        <key>CFBundlePackageType</key>
        <string>APPL</string>
        <key>CFBundleShortVersionString</key>
        <string>rel_2_4_0</string>
        <key>CFBundleVersion</key>
        <string>rel_2_4_0.rel_2_4_0</string>
        <key>NSAppleScriptEnabled</key>
        <true/>
	<key>CFBundleTypeIconFile</key>
        <string>Evergreen.icns</string>
        <key>CFBundleIdentifier</key>
        <string>org.evergreen-ils.Evergreen</string>
</dict>
</plist>
  1. Download and install an appropriate Mac OS package of XULRunner from the Mozilla website (you need xulrunner 14 for Evergreen 2.3+)
  2. Make a copy of /Library/Frameworks/XUL.Framework inside your app file, it should look something like this:
    • Evergreen.app/
      • Contents/
        • Frameworks/
          • XUL.Framework/
            • Versions/
              • Current → 14.0.1 (symlink)
              • 14.0.1/
            • XUL → Versions/Current/XUL
            • libxpcom.dylib → Versions/Current/libxpcom.dylib
            • xulrunner-bin → Versions/Current/xulrunner-bin
  3. copy XUL.Framework/Versions/Current/xulrunner into Evergreen.app/MacOS (do not symlink, copy the file)
  4. Make Evergreen.app/Resources the root of your Evergreen application files like this:
    • Evergreen.app/
      • Contents/
        • Resources/
          • BUILD_ID
          • application.ini
          • chrome/
          • components/
          • etc.
  5. Finally, Put a Mac format icon file named Evergreen.icns in Resources

To stylize the installer, like the example below, http://mac101.net/content/how-to/how-to-create-dmg-art-for-fancy-application-installations/ has great information on styling, and ultimately compressing the installer image. The Evergreen background is provided below, as well.

mozilla-devel/building_the_staff_client.txt · Last modified: 2014/11/10 16:44 by stompro

© 2008-2014 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.