[[user-comments:mozilla-devel:building_the_staff_client|User Comments]] [[mozilla-devel:building_the_staff_client_alpha|Old Alpha release instructions]] [[mozilla-devel:building_the_staff_client_old_world|Instructions for 2.0, 1.6 and earlier]] ====== Building the staff client ====== The staff client server side components are built as part of the "make install" process in a normal load. One can also build them 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". See the instructions below for building the client packages for the staff client, which are not built by default. ===== 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 [[https://developer.mozilla.org/en/Toolkit_version_format|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. ===== STAFF_CLIENT_NAME ===== If you wish to have a custom profile directory you can set the STAFF_CLIENT_NAME to something other than the default of STAFF_CLIENT_NAME=open_ils_staff_client. This can be useful if you want to install multiple clients on one machine and not share preferences between the versions. From staff_client directory: make STAFF_CLIENT_NAME='' build ====== 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 [[http://www.angusj.com/resourcehacker/|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 ==== Custom Install Directory ==== If you wish to customize the install directory for your windows client. This can be useful if you want to run multiple staff clients on one machine without them interacting with each other. Edit the staff_client/windowssetup.nsi file and change the PRODUCT_TAG to a custom value. ;!define /file PRODUCT_VERSION "client/VERSION" !define PRODUCT_TAG "Test-2.8" !define PRODUCT_INSTALL_TAG "${PRODUCT_TAG}" !define UI_IMAGESET "beta" ;!define UI_IMAGESET "release" !define PRODUCT_NAME "Evergreen Staff Client ${PRODUCT_TAG}" Now the default install directory will be c:\%PROGRAMFILES(x86)%\Evergreen Staff Client Test-2.8. Build the staff client after this change is made to activate it. ===== 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 [[mozilla-devel:deploying_automatic_updates|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 [[https://developer.mozilla.org/en/McCoy|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 ===== - 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 - Create a new file in Evergreen.app/Contents/Info.plist with the following (adjust for your version of Evergreen) CFBundleExecutable xulrunner CFBundleGetInfoString OpenILS open_ils_staff_client rel_2_7_5 CFBundleInfoDictionaryVersion 6.0 CFBundleName Evergreen Staff Client CFBundlePackageType APPL CFBundleShortVersionString rel_2_7_5 CFBundleVersion rel_2_7_5.rel_2_7_5 NSAppleScriptEnabled CFBundleIconFile Evergreen.icns CFBundleIdentifier org.evergreen-ils.Evergreen - Download and install an appropriate Mac OS package of XULRunner from the Mozilla website (you need xulrunner 14 for Evergreen 2.3+) - 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 - copy XUL.Framework/Versions/Current/xulrunner into Evergreen.app/Contents/MacOS (do not symlink, copy the file) - Make Evergreen.app/Resources the root of your Evergreen application files like this: * Evergreen.app/ * Contents/ * Resources/ * BUILD_ID * application.ini * chrome/ * components/ * etc. - Finally, Put a Mac format icon file named [[http://evergreen-ils.org/~csharp/Evergreen.icns|Evergreen.icns]] in Resources {{:mozilla-devel:structure.png?300|}} 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:installer.png?300|}} {{:mozilla-devel:background.png|}}