</indexterm>
<section xml:id="staffclientinstallation-installing-prebuilt">
<title>Installing a Pre-Built Staff Client</title>
- <para>A pre-built Staff Client is available for Windows, Mac or Linux systems. Installing the
- Staff Client in each of these environments is described in the following sections.</para>
+ <para>A pre-built Staff Client is available for <systemitem class="osname">Windows</systemitem>,
+ <systemitem class="osname">Mac</systemitem> or Linux systems. Installing the Staff Client in
+ each of these environments is described in the following sections.</para>
<section xml:id="staffclientinstallation-installing-windows">
- <title>Installing on Windows</title>
+ <title>Installing on <systemitem class="osname">Windows</systemitem></title>
<indexterm>
<primary>staff client</primary>
<secondary>installing</secondary>
<tertiary>Windows</tertiary>
</indexterm>
<para>In this section we describe the process of installing the Staff Client on the
- <systemitem class="osname">Microsoft Windows</systemitem> operating
- system.</para>
- <para>Visit the downloads section of the Evergreen website at
+ <systemitem class="osname">Microsoft Windows</systemitem> operating system.</para>
+ <para>Visit the downloads section of the Evergreen website at
<ulink url="http://www.evergreen-ils.org/downloads.php">http://www.evergreen-ils.org/downloads.php</ulink>
- and find the standard Microsoft Windows Installer that contains the current version of
- the Staff Client. Download the Installer, then run it. A screen that looks similar to
- this should appear:</para>
+ and find the standard <systemitem class="osname">Microsoft Windows</systemitem> Installer
+ that contains the current version of the Staff Client. Download the Installer, then run
+ it. A screen that looks similar to this should appear:</para>
<mediaobject>
<alt>
<phrase>Running the Staff Client installer</phrase>
<xref linkend="staffclientinstallation-workstationnames"/>.</para>
</section>
<section xml:id="staffclientinstallation-installing-macos">
- <title>Installing on Mac OS</title>
+ <title>Installing on <systemitem class="osname">Mac OS</systemitem></title>
<indexterm>
<primary>staff client</primary>
<secondary>installing</secondary>
<tertiary>Mac OS</tertiary>
</indexterm>
- <para>In this section, we describe Mac packages and related versions of XULRunner
- that can be used to run the Staff Client in a Mac OS environment.</para>
+ <para>This section describes <systemitem class="osname">Mac OS</systemitem>
+ packages and related versions of <application>XULrunner</application> that can
+ be used to run the Staff Client in a <systemitem class="osname">Mac OS</systemitem>
+ environment.</para>
<simplesect>
<title>Evergreen Version 1.2.3.0</title>
<orderedlist>
<listitem>
- <para>A Mac package that contains an early version of the Staff Client
- (version 1.2.3.0) for use with XULRunner is available. Current releases
- of XULRunner can be found here:
+ <para>A <systemitem class="osname">Mac OS</systemitem> package that
+ contains an early version of the Staff Client (version 1.2.3.0) for use
+ with <application>XULrunner</application> is available. You can find
+ current releases of <application>XULrunner</application> here:
<ulink url="http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases">
http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases</ulink> .
- Download and install the latest version. Further information about
- XULRunner can be found here:
+ Download and install the latest version. You can find further information
+ about <application>XULrunner</application> here:
<ulink url="https://developer.mozilla.org/en/xulrunner">
- https://developer.mozilla.org/en/xulrunner</ulink></para>
- <para>Note that later versions of XULRunner (e.g., version 1.9.2.13) have
- replaced version 1.8.0.4, which has known security holes and is not
- recommended for applications that deal with public web content.</para>
+ https://developer.mozilla.org/en/xulrunner</ulink>.</para>
+ <para>Note that later versions of <application>XULrunner</application>
+ (e.g., version 1.9.2.13) have replaced version 1.8.0.4, which has known
+ security holes and is not recommended for applications that deal with
+ public web content.</para>
</listitem>
<listitem>
- <para>A Mac OS Installation package for Staff Client version 1.2.3.0
- is available from Evergreen Indiana. Download and install it from here:
+ <para>A <systemitem class="osname">Mac OS</systemitem>
+ Installation package for Staff Client version 1.2.3.0 is
+ available from Evergreen Indiana. Download and install it from
+ here:
<ulink url="http://evergreen.lib.in.us/opac/extras/files/evergreen_osx_staff_client_1_2_3.zip">
evergreen_osx_staff_client_1_2_3.zip</ulink> .
</para>
<listitem>
<para>To upgrade to a more recent version of the Staff Client, you can
copy the <filename class="directory">build</filename> directory from a
- working Windows installation of the desired version of the Staff Client
- to your Mac. The required files may be located in a directory like this
- on the Windows machine: <filename class="directory">
- C:\Program Files\Evergreen Staff Client\build</filename>.
+ working <systemitem class="osname">Windows</systemitem> installation of
+ the desired version of the Staff Client to your
+ <systemitem class="osname">Mac</systemitem>.
+ The required files may be located in a directory like this on the
+ <systemitem class="osname">Windows</systemitem> machine:
+ <filename class="directory">C:\Program Files\Evergreen Staff Client\build</filename>.
Copy these files to the <filename class="directory">Resources</filename>
folder within the <package>Open-ILS</package> package in your
<filename class="directory">Applications</filename> directory on the Mac,
similar to this:</para>
<mediaobject>
<alt>
- <phrase>Running the Staff Client installer for Mac OS</phrase>
+ <phrase>Running the Staff Client installer for
+ <systemitem class="osname">Mac OS</systemitem></phrase>
</alt>
<imageobject>
<imagedata fileref="../media/staffclientinstallation-staffclient-3.png" format="PNG" scalefit="1" width="20%"/>
</mediaobject>
</simplesect>
<simplesect>
- <title>Running directly using XULRunner</title>
+ <title>Running directly using <application>XULrunner</application></title>
<indexterm>
<primary>staff client</primary>
<secondary>XULRunner</secondary>
</indexterm>
- <para>You must install an apropriate version of XULRunner to match the Evergreen
- version. See the following table for the recommended version of
- XULRunner:</para>
- <table>
- <title>Evergreen / XULRunner Dependencies</title>
+ <para>You must install an appropriate version of <application>XULrunner</application>
+ to match the Evergreen version. See the following table for the recommended version of
+ <application>XULrunner</application>:</para>
+ <table xml:id="staffclientinstallation-table-1">
+ <title>Evergreen / <application>XULrunner</application> Dependencies</title>
<tgroup align="left" cols="2" colsep="1" rowsep="1">
<colspec colnum="1" colwidth="1.0*"/>
<colspec colnum="2" colwidth="3.0*"/>
<tbody>
<row>
<entry>Evergreen 1.6.x.x</entry>
- <entry>XULrunner 1.9</entry>
+ <entry>XULrunner 1.9.x.x</entry>
</row>
<row>
<entry>Evergreen 1.4.x.x</entry>
</tbody>
</tgroup>
</table>
- <note>If you have issues removing previously installed XULRunner versions see
- <xref linkend="staffclientinstallation-remove-xulrunner"/> for further
- information.
- </note>
+ <note>If you have issues removing previously installed
+ <application>XULrunner</application> versions see
+ <xref linkend="staffclientinstallation-remove-xulrunner"/>
+ for further information.</note>
<para>The Staff Client data from the directory
<filename class="directory">./staff_client/build</filename> must be placed
- somewhere on the machine
- (e.g. <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>).
- Remember to call XULRunner with the full path to the binary, followed by the
- install command and the path to the client data:</para>
+ somewhere on the machine (e.g.
+ <filename class="directory">~/Desktop/Evergreen_Staff_Client</filename>).</para>
+ <para>Remember to call <application>XULrunner</application> with the full path to the
+ binary, followed by the install command and the path to the client data:</para>
<screen>
- <prompt># as the root user</prompt>
<userinput>/Library/Frameworks/XUL.framework/xulrunner-bin --install-app ~/Desktop/Evergreen_Staff_Client</userinput>
</screen>
- <para>This command should exit quietly. The folder
- <filename class="directory">/Applications/OpenILS</filename> will be created,
+ <para>The command should exit quietly and will create the folder
+ <filename class="directory">/Applications/OpenILS</filename>,
containing a launcher named <application>open_ils_staff_client</application>.</para>
</simplesect>
<simplesect xml:id="staffclientinstallation-remove-xulrunner">
- <title>Removing previously installed XULRunner versions</title>
+ <title>(OPTIONAL) Removing previously installed XULRunner versions</title>
<indexterm>
<primary>XULRunner</primary>
<secondary>removing previous versions</secondary>
</indexterm>
- <para>If you already have a newer version installed, per the release notes, you
- will need to remove the entire directory
+ <para>If you already have a newer version of
+ <application>XULrunner</application> installed, per the release notes,
+ you will need to remove the entire directory
<filename class="directory">/Library/Frameworks/XUL.framework</filename>
before downgrading.</para>
- <para>In addition, you may also need to remove the previous
- file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>
+ <para>In addition, you may also need to remove the previous file
+ <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>
<para>If file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> does
- not exist (possibly in newer OSX releases), you need to flush the file
- <filename>receiptdb</filename>.</para>
- <note>If you install a newer version over a previous (older) install, the older
- one is not removed but the symlinks are changed to the newer one.</note>
+ not exist (possibly in newer <systemitem class="osname">Mac OS</systemitem>
+ releases), you need to flush the file <filename>receiptdb</filename>.</para>
+ <note>If you install a newer version of <application>XULrunner</application>
+ over a previous (older) install, the older install is not removed but the
+ symlinks are changed to the newer one.</note>
</simplesect>
<simplesect>
- <title>Flush Receiptdb file:</title>
+ <title>(OPTIONAL) Flush Receiptdb file:</title>
<para>First, get the package identifier, then purge/forget the build that was
initially installed:</para>
<screen>
- <prompt># as the root user</prompt>
<userinput>sudo pkgutil --pkgs > /tmp/pkgs.txt</userinput>
<userinput>sudo pkgutil --forget org.mozilla.xulrunner</userinput>
</screen>
for more information.</note>
</simplesect>
<simplesect>
- <title>Creating an APP file: Staff Client & XULRunner Bundled</title>
+ <title>Creating an APP file: Staff Client and <application>XULrunner</application> Bundled</title>
<para>An APP file is basically a folder. Start with a folder stucture like this:</para>
<screen>
- * Evergreen.app
- * Contents
- * Frameworks
- * Resources
- * MacOS
+ <prompt>Evergreen.app</prompt>
+ <prompt>__Contents</prompt>
+ <prompt>____Frameworks</prompt>
+ <prompt>____Resources</prompt>
+ <prompt>____MacOS</prompt>
</screen>
<para>Create an APP folder structure with the following commands:</para>
<screen>
- <prompt># as the root user</prompt>
<userinput>mkdir -p Evergreen.app/Contents/Frameworks</userinput>
<userinput>mkdir -p Evergreen.app/Contents/Resources</userinput>
<userinput>mkdir -p Evergreen.app/Contents/MacOS</userinput>
</screen>
- <para/>
<orderedlist>
<listitem>
<para>Create a new file in the folder
<key>CFBundleExecutable</key>
<string>xulrunner</string>
<key>CFBundleGetInfoString</key>
- <string>OpenILS open_ils_staff_client rel_1_6_0_7</string>
+ <string>OpenILS open_ils_staff_client rel_1_6_1_2</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleName</key>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
- <string>rel_1_6_0_7</string>
+ <string>rel_1_6_1_2</string>
<key>CFBundleVersion</key>
- <string>rel_1_6_0_7.rel_1_6_0_7</string>
+ <string>rel_1_6_1_2.rel_1_6_1_2</string>
<key>NSAppleScriptEnabled</key>
<true/>
<key>CFBundleTypeIconFile</key>
</plist>
]]></programlisting>
</listitem>
- <listitem>Download and install an appropriate Mac OS package of
- XULRunner from the Mozilla website (see above for
- recommendations).</listitem>
+ <listitem>Download and install an appropriate
+ <systemitem class="osname">Mac OS</systemitem> package of
+ <application>XULrunner</application> from the Mozilla website
+ <ulink url="https://developer.mozilla.org/en/xulrunner">
+ https://developer.mozilla.org/en/xulrunner</ulink> (see
+ <xref linkend="staffclientinstallation-table-1"/> for recommendations).</listitem>
<listitem>
<para>Make a copy of the folder
<filename class="directory">/Library/Frameworks/XUL.Framework</filename>
inside your APP file. It should look something like this:</para>
<screen>
- <prompt>* Evergreen.app/</prompt>
- <prompt>__* Contents/</prompt>
- <prompt>____* Frameworks/</prompt>
- <prompt>______* XUL.Framework/</prompt>
- <prompt>______* Versions/</prompt>
- <prompt>________* Current -> 1.9.1.3 (symlink)</prompt>
- <prompt>________* 1.9.1.3/</prompt>
- <prompt>______* XUL -> Versions/Current/XUL</prompt>
- <prompt>______* libxpcom.dylib -> Versions/Current/libxpcom.dylib</prompt>
- <prompt>______* xulrunner-bin -> Versions/Current/xulrunner-bin</prompt>
+ <prompt>Evergreen.app/</prompt>
+ <prompt>__Contents/</prompt>
+ <prompt>____Frameworks/</prompt>
+ <prompt>______XUL.Framework/</prompt>
+ <prompt>______Versions/</prompt>
+ <prompt>________Current -> 1.9.1.3 (symlink)</prompt>
+ <prompt>________1.9.1.3/</prompt>
+ <prompt>______XUL -> Versions/Current/XUL</prompt>
+ <prompt>______libxpcom.dylib -> Versions/Current/libxpcom.dylib</prompt>
+ <prompt>______xulrunner-bin -> Versions/Current/xulrunner-bin</prompt>
</screen>
</listitem>
<listitem>Copy
<para>Make <filename>Evergreen.app/Resources</filename> the root
of your Evergreen application files like this:</para>
<screen>
- <prompt>* Evergreen.app/</prompt>
- <prompt>__* Contents/</prompt>
- <prompt>____* Resources/</prompt>
- <prompt>______* BUILD_ID</prompt>
- <prompt>______* application.ini</prompt>
- <prompt>______* chrome/</prompt>
- <prompt>______* components/</prompt>
- <prompt>______* etc.</prompt>
+ <prompt>Evergreen.app/</prompt>
+ <prompt>__Contents/</prompt>
+ <prompt>____Resources/</prompt>
+ <prompt>______BUILD_ID</prompt>
+ <prompt>______application.ini</prompt>
+ <prompt>______chrome/</prompt>
+ <prompt>______components/</prompt>
+ <prompt>______etc.</prompt>
</screen>
</listitem>
- <listitem>Put a Mac format icon file named <filename>Evergreen.icns</filename> in
+ <listitem>Put a <systemitem class="osname">Mac</systemitem>
+ format icon file named <filename>Evergreen.icns</filename> in
<filename class="resources">Resources</filename>.</listitem>
</orderedlist>
</simplesect>
<para>A Linux Staff Client is automatically built on the server as part of the
normal <emphasis>make install</emphasis> process for Evergreen server-side
software. To upgrade the Staff Client on a remote Linux workstation with a new
- version, just copy the directory tree containing the Staff Client from the
+ version, just copy the directory tree containing the Staff Client from your
server to the remote workstation.</para>
- <para>The following example assumes you already have an
- <systemitem class="username">opensrf</systemitem> user account on both the
- server and the remote workstation. Replace <literal>USER</literal>,
- <literal>LINUX_MACHINE</literal>, and <literal>HOME_DIRECTORY</literal>
- with appropriate values.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, execute the
- following commands:</para>
+ <para>Execute the following commands, replacing <literal>USER</literal>,
+ <literal>WORKSTATION</literal>, and <literal>SOME_PATH</literal> with
+ appropriate values:</para>
<screen>
- <prompt># as the opensrf user</prompt>
<userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>scp -r ./build USER@LINUX_MACHINE:~/HOME_DIRECTORY/</userinput>
+ <userinput>scp -r ./build USER@WORKSTATION:/SOME_PATH/</userinput>
</screen>
- <para>You must now test the newly copied Staff Client.
- As the <systemitem class="username">opensrf</systemitem> user, log into the
- remote workstation and execute the following command:</para>
+ <para>You should test the newly copied Staff Client on the remote workstation.
+ Log into the workstation and execute the following command:</para>
<screen>
- <prompt># as the opensrf user</prompt>
- <userinput>xulrunner ~/HOME_DIRECTORY/build/application.ini</userinput>
+ <userinput>xulrunner /SOME_PATH/build/application.ini</userinput>
</screen>
</simplesect>
<simplesect>
software. See <xref linkend="serversideinstallation-compile"/> for details of
the build process.</para>
<para>In order to install a compatible Staff Client on another Linux system, you
- can copy the appropriate files from the Staff Client build directory on the
- server to the new Linux system, or just manually build it on the new
- system. Ensure that the BUILD_ID you choose on the new system matches the
- BUILD_ID for each Staff Client you use on other systems.</para>
- <para>If you wish to use a pre-packaged Windows version on some systems, you
- may want to choose the BUILD_ID on both server and other versions to match that
- of the Windows Staff Client. To determine which BUILD_ID used in an existing
- Staff Client installation, execute the Staff Client and click
- <guibutton>'About this Client'</guibutton>.</para>
+ can copy the appropriate files from the Staff Client build directory on your
+ server to the new Linux system. You could manually build the Staff Client on the
+ new system, but you must ensure that the <envar>BUILD_ID</envar> you chose on
+ the server matches the <envar>BUILD_ID</envar> for each Staff Client you use on
+ other systems.</para>
+ <para>If you wish to use a pre-packaged <systemitem class="osname">Windows</systemitem>
+ version on some systems, you may want to choose the <envar>BUILD_ID</envar> on
+ both server and other versions to match that of the
+ <systemitem class="osname">Windows</systemitem> Staff Client. To determine which
+ <envar>BUILD_ID</envar> was used for existing Staff Client installations,
+ execute each Staff Client and click the <guibutton>'About this Client'</guibutton>
+ button.</para>
<para>If you are allowed to make changes on the Evergreen server, another option
is to create a symbolic link. In order for a copy of the Staff Client and server
- to work together, the BUILD_ID must match the name of the directory containing
- the server components of the Staff Client, or the name of a symbolic link to
- that directory.</para>
+ to work together, the <envar>BUILD_ID</envar> must match the name of the
+ directory containing the server components of the Staff Client, or the name of a
+ symbolic link to that directory. As the
+ <systemitem class="username">root</systemitem> user, make the changes as follows:</para>
<screen>
<prompt># as the root user</prompt>
<userinput>cd /openils/var/web/xul</userinput>
</screen>
</simplesect>
<simplesect>
- <title>Building the Staff Client on a client Machine</title>
- <para>This section is directed toward end-users who wish to use Linux rather
- than Windows for client machines, but have limited Linux experience. You can
- build the Staff Client on a Linux system without installing the Evergreen Server
- component. This is a relatively simple process compared to server installation,
- but does require some command-line work. The following directions are for
- building Staff Client version 1.2.1.4 on Kubuntu 7.10; you must modify them for
- other distributions (the instructions should work as-is for Ubuntu or Ubuntu
- derivatives).</para>
+ <title>Building the Staff Client on a Client Machine</title>
+ <para>This section is directed toward end-users who wish to use Linux rather than
+ <systemitem class="osname">Windows</systemitem> for client machines, but have limited
+ Linux experience. You can build the Staff Client on a Linux system without installing the
+ Evergreen Server component. This is a relatively simple process compared to server
+ installation, but does require some command-line work. The following instructions are
+ for building Staff Client version 1.2.1.4 on
+ <systemitem class="osname">Kubuntu 7.10</systemitem>; modify them as needed for
+ other distributions (the instructions should work as-is for
+ <systemitem class="osname">Ubuntu</systemitem> or
+ <systemitem class="osname">Ubuntu</systemitem> derivatives).</para>
<procedure>
<step>
<title>Prerequisites</title>
<para>Both <application>subversion</application> and
- <application>xulrunner</application> are required to build the Staff
+ <application>XULrunner</application> are required to build the Staff
Client. As the <systemitem class="username">root</systemitem> user,
use <command>apt-get</command> to install packages for
<application>subversion</application> and
- <application>xulrunner</application>. You can also use
+ <application>XULrunner</application>. You can also use
<command>synaptic</command>, the graphical user interface for
<command>apt-get</command>. For <application>subversion</application>,
- select the latest version; for <application>xulrunner</application>,
+ select the latest version; for <application>XULrunner</application>,
select version <emphasis>1.8.1.4-2ubuntu5</emphasis>.</para>
<screen>
<prompt># as the root user</prompt>
</step>
<step>
<title>Build the Staff Client</title>
- <para>In the following
- example, navigate to the directory in which the source code was
- downloaded, then navigate to the proper subdirectory and run the
- "make" utility to actually build the Staff Client. Remember to
- check with your system administrator about which Staff Client
- BUILD_ID to use. The server checks the Staff Client BUILD_ID
- against itself to determine whether or not a connecting client
- is supported. For instance, for the PINES installation (version
- 1.2.1.4) the supported BUILD_ID is "rel_1_2_1_4". Modify the
- following commands accordingly.</para>
+ <para>In the following example, navigate to the directory in
+ which the source code was downloaded, then navigate to the
+ proper subdirectory and run the "make" utility to actually build
+ the Staff Client. Remember to check with your system
+ administrator about which Staff Client <envar>BUILD_ID</envar>
+ to use. The server checks the Staff Client
+ <envar>BUILD_ID</envar> against itself to determine whether or
+ not a connecting client is supported. For instance, for the
+ PINES installation (version 1.6.1.2) the supported
+ <envar>BUILD_ID</envar> is "rel_1_6_1_2". Modify the following
+ commands accordingly.</para>
<para>As the <systemitem class="username">opensrf</systemitem>
user, run the following commands to build the Staff Client:</para>
<screen>
<prompt># as the opensrf user</prompt>
- <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>
- <userinput>cd Open-ILS/xul/staff_client</userinput>
- <userinput>make STAFF_CLIENT_BUILD_ID='rel_1_6_1_2'</userinput>
+ <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>
+ <userinput>tar xfz Evergreen-ILS-1.6.1.2.tar.gz</userinput>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
+ <userinput>cd ./Open-ILS/xul/staff_client/</userinput>
+ <userinput>make STAFF_CLIENT_BUILD_ID='rel_1_6_1_2' install</userinput>
</screen>
</step>
<step>
- <title>Run the Staff Client (from the command line)</title>
+ <title>Run the Staff Client</title>
<para>As the <systemitem class="username">opensrf</systemitem>
user, navigate to the <filename class="directory">build/</filename>
- subdirectory (not <filename class="directory">staff_client/</filename>)
- and run the following command:</para>
+ subdirectory and run the following command:</para>
<screen>
<prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build</userinput>
<userinput>xulrunner application.ini</userinput>
</screen>
</step>
<step>
- <title>(OPTIONAL) Cleaning Up / Creating Shortcuts</title>
+ <title>(OPTIONAL) Clean Up / Create Shortcuts</title>
<para>The source code download included many files that are
needed to build the Staff Client but are not necessary to run
- it. You may wish to remove them to save space or to create a
- clean directory containing the built Staff Client that can then
- be copied to other machines.</para>
- <para>To create a clean "staging" directory in which to place
- the finished Staff Client, execute the following commands
- (remember to replace <literal>DESTINATION_DIRECTORY</literal>
- with the appropriate path):</para>
+ it. You may wish to remove them to save space, or to create a
+ clean <literal>staging</literal> directory containing the
+ finished Staff Client that can then be copied to other
+ machines. To do this, execute the following commands (remember
+ to replace <literal>DOWNLOAD_DIRECTORY</literal> and
+ <literal>STAGING_DIRECTORY</literal> with the appropriate
+ paths):</para>
<screen>
<prompt># as the opensrf user</prompt>
- <userinput>mkdir ~/DESTINATION_DIRECTORY</userinput>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/</userinput>
- <userinput>cp -r staff_client ~/DESTINATION_DIRECTORY</userinput>
+ <userinput>mkdir ~/STAGING_DIRECTORY</userinput>
+ <userinput>cd ~/DOWNLOAD_DIRECTORY/Open-ILS/xul/</userinput>
+ <userinput>cp -r staff_client ~/STAGING_DIRECTORY</userinput>
</screen>
- <para>Finally, test the Staff Client to verify that all necessary
- files were moved to the destination directory:</para>
+ <para>Test the Staff Client to verify that all necessary files
+ were copied to the staging directory:</para>
<screen>
<prompt># as the opensrf user</prompt>
- <userinput>cd ~/DESTINATION_DIRECTORY/staff_client/build</userinput>
+ <userinput>cd ~/STAGING_DIRECTORY/staff_client/build</userinput>
<userinput>xulrunner application.ini</userinput>
</screen>
- <para>If there were no problems, then finish the cleanup by removing the
- original download directory and all subdirectories as shown:</para>
+ <para>If there were no problems, then finish the cleanup by
+ removing the original download directory as shown:</para>
<screen>
<prompt># as the opensrf user</prompt>
<userinput>rm -r -f ~/DOWNLOAD_DIRECTORY</userinput>
</screen>
- <para>You may wish to create a shortcut for the Staff Client:</para>
- <menuchoice>
- <guimenu>Desktop</guimenu>
- <guimenuitem>StartMenu</guimenuitem>
- <guimenuitem>K-Menu</guimenuitem>
- </menuchoice>
- <para>Use the command: <command>xulrunner
- ~/DESTINATION_DIRECTORY/staff_client/build/application.ini</command>
- as the target for the shortcut.</para>
+ <para>Finally, the command:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>xulrunner ~/STAGING_DIRECTORY/staff_client/build/application.ini</userinput>
+ </screen>
+ <para>will now run the Staff Client. You may wish to create a
+ shortcut for the Staff Client. To do so, use the previous
+ command as the target for the shortcut:
+ <menuchoice><guimenu>Desktop</guimenu><guimenuitem>StartMenu</guimenuitem><guimenuitem>K-Menu</guimenuitem></menuchoice></para>
</step>
</procedure>
</simplesect>
<primary>staff client</primary>
<secondary>using wine to install on Linux</secondary>
</indexterm>
- <para>The Linux application <application>Wine</application> is another alternative if you
- wish to install the packaged Windows versions rather than building the Staff Client
- manually. Wine is a Linux application that allows users to directly run Windows
- executables, and is a simple way for casual Linux users to use the Staff Client. More
- information about Wine can be found at
+ <para>The Linux application <application>Wine</application> is another
+ alternative if you wish to install the packaged
+ <systemitem class="osname">Windows</systemitem> versions rather than manually
+ building the Staff Client. <application>Wine</application> is a Linux
+ application that allows users to directly run
+ <systemitem class="osname">Windows</systemitem> executables, and is a simple
+ way for casual Linux users to use the Staff Client. You can find more information
+ about <application>Wine</application> at
<ulink url="http://www.winehq.org/site/docs/wineusr-guide/getting-wine">
http://www.winehq.org/site/docs/wineusr-guide/getting-wine</ulink>.</para>
<para>As the <systemitem class="username">root</systemitem> user, use
</screen>
</listitem>
<listitem>
- <para>Download Windows installer for the Staff Client</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, run
- the following commands to download the Windows installer for the proper
- Staff Client from the <ulink url="http://open-ils.org">open-ils.org</ulink>
- website and place it in a temporary directory:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>
- <userinput>wget http://open-ils.org/downloads/evergreen-setup-rel_version-number.exe</userinput>
- </screen>
+ <para>Visit the downloads section of the Evergreen website at
+ <ulink url="http://www.evergreen-ils.org/downloads.php">
+ http://www.evergreen-ils.org/downloads.php</ulink> and find the
+ <systemitem class="osname">Microsoft Windows</systemitem> Installer
+ that contains the desired version of the Staff Client. Download
+ the installer and place it in a temporary directory.</para>
</listitem>
<listitem>
- <para>Run the downloaded Windows installer</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user,
- navigate to the directory where you downloaded the Windows executable
- file, then execute it:</para>
+ <para>As the <systemitem class="username">opensrf</systemitem>
+ user, navigate to the temporary directory where you downloaded
+ the <systemitem class="osname">Windows</systemitem> installer
+ file, then execute it with the <application>wine</application>
+ application (remember to replace <literal>VERSION</literal> with
+ the release number of the Staff Client you downloaded):</para>
<screen>
<prompt># as the opensrf user</prompt>
- <userinput>cd /YOUR/DOWNLOAD/DIRECTORY</userinput>
- <userinput>wine evergreen-setup-rel_version-number.exe</userinput>
+ <userinput>cd /TEMP_DIRECTORY</userinput>
+ <userinput>wine evergreen-setup-rel_VERSION.exe</userinput>
</screen>
- <para>If this step fails, you may need to configure Wine first to properly
- emulate Windows XP. To do so, type "winecfg" from the command line; in the
- "Applications" tab of the window that pops up, select "Default Settings"
- and choose "Windows XP" from the drop-down menu, then click
- <guibutton>'Apply'</guibutton>.</para>
- </listitem>
- <listitem>
- <para>Launch the Staff Client</para>
- <para>A new entry for the Staff Client should now appear somewhere in the
- "All Applications" menu of your Linux desktop. Also, find a new desktop
- shortcut for the Staff Client. To launch the Staff Client, visit the "All
- Applications" menu, find a section similar to "Wine->Program
- Files->Evergreen Staff Client->Evergreen Staff Client", or else launch the
- Staff Client from the desktop shortcut.</para>
+ <para>If this step fails, you may need to configure
+ <application>Wine</application> first to properly emulate
+ <systemitem class="osname">Windows XP</systemitem>. To do so,
+ type <command>winecfg</command> from the command line; in the
+ <literal>Applications</literal> tab of the window that pops up,
+ select <literal>Default Settings</literal> and choose
+ <literal>Windows XP</literal> from the drop-down menu, then
+ click <guibutton>'Apply'</guibutton>.</para>
</listitem>
+ <listitem><para>Launch the Staff Client</para> <para>A new entry for the
+ Staff Client should now appear somewhere in the <literal>All
+ Applications</literal> menu of your Linux desktop. You may also
+ find a new desktop shortcut for the Staff Client. To launch the
+ Staff Client, visit the your desktop's <literal>All
+ Applications</literal> menu and find the section similar to
+ <menuchoice><guimenu>Wine</guimenu><guimenuitem>Program Files</guimenuitem><guimenuitem>Evergreen Staff Client</guimenuitem><guimenuitem>Evergreen Staff Client</guimenuitem></menuchoice>
+ or else launch the Staff Client from the new desktop shortcut.</para></listitem>
</orderedlist>
</simplesect>
- <simplesect xml:id="staffclientinstallation-workstationnames">
- <title>Assigning Workstation Names</title>
- <indexterm>
- <primary>staff client</primary>
- <secondary>assigning workstation names</secondary>
- </indexterm>
- <para>The Staff Client must be assigned to a library and given a unique name before it
- will connect fully to the Evergreen server. The only restriction is that the workstation's
- name must be unique within the assigned library. Make sure to select a workstation name
- that you will remember later, and reflects the role, purpose, and/or location of a
- particular computer. These names will come up later in statistical reporting, and can also
- be handy when troubleshooting.</para>
- <mediaobject>
- <alt>
- <phrase>Example of unconfigured Staff Client</phrase>
- </alt>
- <imageobject>
- <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="70%"/>
- </imageobject>
- </mediaobject>
- <para>In order to assign a workstation a name, a user with appropriate permissions must
- login to the Staff Client. In PINES, the local system administrator (OPSM) has the ability
- to assign workstation names in their library system. Library managers (LIBM's) have the
- ability within their branch. To assign a workstation a name, login to the system. You will
- be prompted to assign the workstation a library and a name:</para>
- <mediaobject>
- <alt>
- <phrase>Example of configured Staff Client</phrase>
- </alt>
- <imageobject>
- <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="70%"/>
- </imageobject>
- </mediaobject>
- <para>Select the library this workstation physically operates in from the drop down
- menu. In this example, we have selected "MGRL-MA". Type in a friendly name for the
- workstation. In this example, we are installing the Staff Client on the director's
- personal system, and have named it as such. Then click
- <guibutton>'Register'</guibutton>.</para>
- <para>Once you have registered your workstation
- with the server, your screen will look like this:</para>
- <mediaobject>
- <alt>
- <phrase>Example of registered Staff Client</phrase>
- </alt>
- <imageobject>
- <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="70%"/>
- </imageobject>
- </mediaobject>
- <para>You are now ready to log into the Staff Client for the first time. Type in your
- password again, and click <guibutton>'Login'</guibutton>.</para>
- </simplesect>
- </section>
- <section>
- <title>Building the Staff Client</title>
- <indexterm>
- <primary>staff client</primary>
- <secondary>building</secondary>
- </indexterm>
- <para>You can also manually build the Staff Client by using the <command>make</command>
- utility in the Staff Client source directory (e.g., the directory
- <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.0.x/Open-ILS/xul/staff_client</filename>
- for the current Evergreen version). There are a number of possible options to manually
- build special versions of the Staff Client on a Linux system. Following is a list of
- environment variables that can be passed to <command>make</command> to influence the
- manual build process:</para>
- <simplesect>
- <title>Option STAFF_CLIENT_BUILD_ID</title>
- <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
- software build process, the variable defaults to an automatically generated
- date/time string, but you can also override the value of BUILD_ID.</para>
- <para>The following commands could be used during the normal build process:</para>
- <screen>
- <prompt># as the root user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>make STAFF_CLIENT_BUILD_ID=1.6.1.2 install</userinput>
- </screen>
- <para>The following commands will manually build the Staff Client using a different BUILD_ID.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to the Staff
- Client source directory, then set the variable and build the Staff Client:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make STAFF_CLIENT_BUILD_ID=my_test_id build</userinput>
- </screen>
- </simplesect>
- <simplesect>
- <title>Option STAFF_CLIENT_VERSION</title>
- <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
- software build process, the variable is pulled automatically from a README file
- in the Evergreen source root. The variable defaults to
- <emphasis>0trunk.revision</emphasis>, where the value of "revision" is
- automatically generated. You can override the value of VERSION similarly to the
- BUILD_ID.</para>
- <para>The following commands could be used during the normal build process:</para>
- <screen>
- <prompt># as the root user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>make STAFF_CLIENT_VERSION=0mytest.200 install</userinput>
- </screen>
- <para>The following commands will manually build the Staff Client using a different VERSION.</para>
- <para>If you plan to make extensions update automatically, the VERSION needs to
- conform to the format recommended in
- <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">
- Toolkit Version Format</ulink> and newer versions need to be "higher" than older
- versions.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change
- directory to the Staff Client source directory, then set the variable and build
- the Staff Client:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make STAFF_CLIENT_VERSION=0mytest.200 build</userinput>
- </screen>
- </simplesect>
- <simplesect>
- <title>Option STAFF_CLIENT_STAMP_ID variable</title>
- <para>During the normal <emphasis>make install</emphasis> Evergreen server-side software
- build process, this variable is generated from STAFF_CLIENT_VERSION. You can override the
- value of STAMP_ID similarly to the BUILD_ID.</para>
- <para>The following commands could be used during the normal build process:</para>
- <screen>
- <prompt># as the root user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput>
- </screen>
- <para>The following commands will manually build the Staff Client using a
- different STAMP_ID.</para>
- <para>It is possible to have multiple versions of the
- Staff Client by specifying a different STAMP_ID for each, possibly for different
- uses or client-side customizations.</para>
- <para>As the <systemitem class="username">opensrf</systemitem>
- user, change directory to the Staff Client source directory, then set the variable and
- build the Staff Client:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput>
- </screen>
- </simplesect>
</section>
- <section>
- <title>Advanced Build Options</title>
- <indexterm>
- <primary>staff client</primary>
- <secondary>building</secondary>
- <tertiary>advanced build options</tertiary>
- </indexterm>
- <para>In addition to the basic options listed above, there are a number of advanced options for
- building the Staff Client. Most are target names for the <command>make</command> utility and
- require that you build the Staff Client from its source directory. See the following table for a
- list of possible <command>make</command> target keywords:</para>
+ </section>
+ <section>
+ <title>Building the Staff Client</title>
+ <indexterm>
+ <primary>staff client</primary>
+ <secondary>building</secondary>
+ </indexterm>
+ <para>You can also manually build the Staff Client by using the <command>make</command>
+ utility in the Staff Client source directory (e.g., the directory
+ <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</filename>
+ for the current Evergreen version). There are a number of possible options to manually
+ build special versions of the Staff Client on a Linux system. Following is a list of
+ variables that you can pass to <command>make</command> to influence the manual build
+ process:</para>
+ <simplesect>
+ <title>
+ <envar>STAFF_CLIENT_BUILD_ID</envar>
+ </title>
+ <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
+ software build process, the variable defaults to an automatically generated
+ date/time string, but you can also override the value of <envar>BUILD_ID</envar>.</para>
+ <para>You could use the following commands during the normal install process:</para>
+ <screen>
+ <prompt># as the root user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>make STAFF_CLIENT_BUILD_ID=1_6_1_2 install</userinput>
+ </screen>
+ <para>You can also manually build the Staff Client in the Staff Client
+ source directory with a different <envar>BUILD_ID</envar>.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands to build the Staff Client (remember to replace
+ <literal>NEW_VERSION</literal> with an appropriate value):</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make STAFF_CLIENT_BUILD_ID=NEWVERSION build</userinput>
+ </screen>
+ </simplesect>
+ <simplesect>
+ <title>
+ <envar>STAFF_CLIENT_VERSION</envar>
+ </title>
+ <para>During the normal <emphasis>make install</emphasis> Evergreen server-side
+ software build process, the variable is pulled automatically from a README file
+ in the Evergreen source root. The variable defaults to
+ <emphasis>0trunk.revision</emphasis>, where the value of "revision" is
+ automatically generated. You can override the value of <envar>VERSION</envar>
+ similarly to the <envar>BUILD_ID</envar>.</para>
+ <para>You could use the following commands during the normal install process:</para>
+ <screen>
+ <prompt># as the root user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>make STAFF_CLIENT_VERSION=0mytest.200 install</userinput>
+ </screen>
+ <para>You can also manually build the Staff Client in the Staff Client
+ source directory with a different <envar>VERSION</envar>.</para>
+ <para>If you plan to make extensions update automatically, the
+ <envar>VERSION</envar> needs to conform to the format recommended in
+ <ulink url="https://developer.mozilla.org/en/Toolkit_version_format">
+ Toolkit Version Format</ulink> and newer versions need to be "higher" than older
+ versions.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands to build the Staff Client:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make STAFF_CLIENT_VERSION=0mytest.200 build</userinput>
+ </screen>
+ </simplesect>
+ <simplesect>
+ <title>
+ <envar>STAFF_CLIENT_STAMP_ID</envar>
+ </title>
+ <para>During the normal <emphasis>make install</emphasis> Evergreen
+ server-side software build process, the variable is generated from
+ <envar>STAFF_CLIENT_VERSION</envar>. You may want to have multiple versions
+ of the Staff Client with different stamps, possibly for different uses or
+ client-side customizations. You can override the value of
+ <envar>STAMP_ID</envar> similarly to the <envar>BUILD_ID</envar>.</para>
+ <para>You could use the following commands during the normal install process:</para>
+ <screen>
+ <prompt># as the root user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp install</userinput>
+ </screen>
+ <para>You can also manually build the Staff Client in the Staff Client
+ source directory with a different <envar>STAMP_ID</envar>.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands to build the Staff Client:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make STAFF_CLIENT_STAMP_ID=my_test_stamp build</userinput>
+ </screen>
+ </simplesect>
+ </section>
+ <section>
+ <title>Advanced Build Options</title>
+ <indexterm>
+ <primary>staff client</primary>
+ <secondary>building</secondary>
+ <tertiary>advanced build options</tertiary>
+ </indexterm>
+ <para>In addition to the basic options listed above, there are a number of advanced
+ options for building the Staff Client. Most are target names for the
+ <command>make</command> utility and require that you build the Staff Client from the
+ <literal>staff_client</literal> directory. See the following table for a list of
+ possible <command>make</command> target keywords:</para>
+ <table>
+ <title>Keywords Targets for "make" Command</title>
+ <tgroup align="left" cols="2" colsep="1" rowsep="1">
+ <colspec colnum="1" colwidth="1.0*"/>
+ <colspec colnum="2" colwidth="3.0*"/>
+ <thead>
+ <row>
+ <entry>Keyword</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>clients</entry>
+ <entry>Runs "make win-client", "make linux-client", and "make
+ generic-client" individually</entry>
+ </row>
+ <row>
+ <entry>client_dir</entry>
+ <entry>Builds a client directory from the build directory, without
+ doing a rebuild. The same as "copy everything but
+ server/".</entry>
+ </row>
+ <row>
+ <entry>client_app</entry>
+ <entry>Prerequisite "client_dir"; removes "install.rdf" from
+ client directory so an APP bundle can't be installed as an
+ extension</entry>
+ </row>
+ <row>
+ <entry>client_ext</entry>
+ <entry>Prerequisite "client_dir"; remove "application.ini",
+ "autoupdate.js", "standalone_xul_app.js" from client directory so
+ an extension won't break Firefox</entry>
+ </row>
+ <row>
+ <entry>extension</entry>
+ <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry>
+ </row>
+ <row>
+ <entry>generic-client</entry>
+ <entry>Prerequisite "client_app"; makes an XPI file suitable for
+ use with "xulrunner --install-app""</entry>
+ </row>
+ <row>
+ <entry>win-xulrunner</entry>
+ <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry>
+ </row>
+ <row>
+ <entry>linux-xulrunner</entry>
+ <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry>
+ </row>
+ <row>
+ <entry>win-client</entry>
+ <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires
+ that "nsis" package be installed, will add options for automatic
+ update if configured and developer options if client build was a
+ "make devbuild")</entry>
+ </row>
+ <row>
+ <entry>linux-client</entry>
+ <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle
+ of the Linux client</entry>
+ </row>
+ <row>
+ <entry>[generic-|win-|linux-|extension-]updates[-client]</entry>
+ <entry>Calls external/make_updates.sh to build full and partial
+ updates generic/win/linux/extension prefix limit to that
+ distribution; Adding <option>-client</option> builds clients and
+ copies them to a subdirectory of the
+ <filename class="directory">updates</filename> directory as well;
+ <option>extension-updates-client</option> doesn't exist.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Following are descriptions of other special build options:</para>
+ <simplesect>
+ <title>Developer Build</title>
+ <para>You can create a so-called <emphasis>developer build</emphasis>
+ of the Staff Client by substituting <option>devbuild</option> for
+ <option>build</option> when running <command>make</command> from the
+ <literal>staff_client</literal> directory. The build will contain an
+ extra configuration file that enables some developer options.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, run
+ the following commands from the Staff Client source directory:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make devbuild</userinput>
+ </screen>
+ </simplesect>
+ <simplesect>
+ <title>Compressed Javascript</title>
+ <para>You can execute the Google <systemitem class="resource">Closure Compiler</systemitem>
+ utility to automatically review and compress Javascript code after the build
+ process completes, by substituting <option>compress-javascript</option> for
+ <option>build</option> when running <command>make</command>.
+ For more information on the Google Closure Compiler, see
+ <ulink url="http://code.google.com/closure/compiler/">
+ http://code.google.com/closure/compiler</ulink>.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, run
+ the following commands from the Staff Client source directory:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make compress-javascript</userinput>
+ </screen>
+ <para>You can also combine Javascript review and compression, and also perform a
+ <emphasis>developer build</emphasis>.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, run the
+ following commands from the Staff Client source directory:</para>
+ <note>In the following <command>make</command> below, the order of options is
+ important.</note>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make devbuild compress-javascript</userinput>
+ </screen>
+ </simplesect>
+ <simplesect xml:id="staffclientinstallation-autoupdatehost">
+ <title>Automatic Update Host</title>
+ <para>You can override the host used to check for automatic Staff Client updates
+ by specifying the <option>AUTOUPDATE_HOST</option> option.</para>
+ <para>You could use the following commands during the normal install process:</para>
+ <screen>
+ <prompt># as the root user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>make AUTOUPDATE_HOST=localhost install</userinput>
+ </screen>
+ <para>You can manually build the Staff Client in the Staff Client
+ source directory and set <option>AUTOUPDATE_HOST</option> to enable automatic
+ update checking.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands to build the Staff Client:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make AUTOUPDATE_HOST=localhost build</userinput>
+ </screen>
+ <para>For more information on Automatic Updates, see
+ <xref linkend="staffclientinstallation-autoupdate"/>.</para>
+ </simplesect>
+ </section>
+ <section>
+ <title>Installing and Activating a Manually Built Staff Client</title>
+ <para>The Staff Client is automatically built, installed and activated as part of the
+ normal <command>make<option>install</option></command> process for Evergreen
+ server-side software. However, if you manually build the Staff Client from the
+ <literal>staff_client</literal> directory, then you need to take additional steps to
+ properly install and activate it. You also have the option of installing the Staff
+ Client on the same machine it was built on, or on a different machine.</para>
+ <para>Assuming you have already built the Staff Client, and that your installation is
+ in the directory <filename class="directory">/openils/var/web/xul</filename>, as the
+ <systemitem class="username">opensrf</systemitem> user execute the following
+ commands:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
+ <userinput>cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
+ </screen>
+ </section>
+ <section>
+ <title>Packaging the Staff Client</title>
+ <para>Once you have built the Staff Client, you can create several forms of special client
+ packages by using a modified <command>make</command> command in the <literal>staff_client</literal>
+ directory.</para>
+ <simplesect>
+ <title>Packaging a Generic Client</title>
+ <para>This build creates a Staff Client packaged as an XPI file suitable for use with
+ the <option>--install-app</option> parameter of <application>XULrunner</application>.
+ It requires that you already have the <systemitem>zip</systemitem> utility
+ installed on your system.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, execute
+ the following commands:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make generic-client</userinput>
+ </screen>
+ <para>The output file <filename>evergreen_staff_client.xpi</filename> will be created.</para>
+ </simplesect>
+ <simplesect>
+ <title>Packaging a <systemitem class="osname">Windows</systemitem> Client</title>
+ <para>This build creates a Staff Client packaged as a
+ <systemitem class="osname">Windows</systemitem> executable. It requires that
+ you already have the <application>unzip</application> utility installed on
+ your system. It also requires that you install
+ <ulink url="http://nsis.sourceforge.net/">NSIS (Nullsoft Scriptable Install System)</ulink>,
+ a professional open source utility package used to create
+ <systemitem class="osname">Windows</systemitem> installers (the
+ <application>"makensis"</application> utility is installed as part of the
+ <application>"nsis"</application> package). You should use Version 2.45 or
+ later.</para>
+ <para>If you wish for the Staff Client to have a link icon/tray icon by
+ default, you may wish to provide a pre-modified
+ <application>xulrunner-stub.exe</application>. Place it in the Staff Client
+ source directory and <command>make</command> will automatically use it instead
+ of the one that comes with the downloaded <application>XULrunner</application>
+ release. The version of <application>xulrunner-stub.exe</application> need not
+ match exactly.</para>
+ <para>You can also use a tool such as
+ <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink>
+ to embed icons. <application>Resource Hacker</application> is an open-source
+ utility used to modify resources within 32-bit
+ <systemitem class="osname">Windows</systemitem> executables.
+ Some useful icon ID strings include the following:</para>
<table>
- <title>Keywords Targets for "make" Command</title>
+ <title>Useful icon ID strings</title>
<tgroup align="left" cols="2" colsep="1" rowsep="1">
<colspec colnum="1" colwidth="1.0*"/>
- <colspec colnum="2" colwidth="3.0*"/>
- <thead>
- <row>
- <entry>Keyword</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <colspec colnum="2" colwidth="1.0*"/>
<tbody>
<row>
- <entry>clients</entry>
- <entry>Runs "make win-client", "make linux-client", and "make
- generic-client" individually</entry>
- </row>
- <row>
- <entry>client_dir</entry>
- <entry>Builds a client directory from the build directory, without
- doing a rebuild. The same as "copy everything but
- server/".</entry>
- </row>
- <row>
- <entry>client_app</entry>
- <entry>Prerequisite "client_dir"; removes "install.rdf" from
- client directory so an APP bundle can't be installed as an
- extension</entry>
- </row>
- <row>
- <entry>client_ext</entry>
- <entry>Prerequisite "client_dir"; remove "application.ini",
- "autoupdate.js", "standalone_xul_app.js" from client directory so
- an extension won't break Firefox</entry>
- </row>
- <row>
- <entry>extension</entry>
- <entry>Prerequisite "client_ext"; rewritten to use "client_ext"</entry>
+ <entry>IDI_APPICON</entry>
+ <entry>Tray icon</entry>
</row>
<row>
- <entry>generic-client</entry>
- <entry>Prerequisite "client_app"; makes an XPI file suitable for
- use with "xulrunner --install-app""</entry>
- </row>
- <row>
- <entry>win-xulrunner</entry>
- <entry>Prerequisite "client_app"; adds Windows xulrunner to client build</entry>
- </row>
- <row>
- <entry>linux-xulrunner</entry>
- <entry>Prerequisite "client_app"; adds Linux xulrunner to client build</entry>
- </row>
- <row>
- <entry>win-client</entry>
- <entry>Prerequisite "win-xulrunner"; builds "setup exe" (requires
- that "nsis" package be installed, will add options for automatic
- update if configured and developer options if client build was a
- "make devbuild")</entry>
- </row>
- <row>
- <entry>linux-client</entry>
- <entry>Prerequisite "linux_xulrunner"; builds a "tar.bz2" bundle
- of the Linux client</entry>
- </row>
- <row>
- <entry>[generic-|win-|linux-|extension-]updates[-client]</entry>
- <entry>Calls external/make_updates.sh to build full and partial
- updates generic/win/linux/extension prefix limit to that
- distribution; Adding <option>-client</option> builds clients and
- copies them to a subdirectory of the
- <filename class="directory">updates</filename> directory as well;
- <option>extension-updates-client</option> doesn't exist.</entry>
+ <entry>32512</entry>
+ <entry>Default window icon</entry>
</row>
</tbody>
</tgroup>
</table>
- <para>Descriptions of other special build options follow:</para>
- <itemizedlist>
- <listitem>
- <para>Developer Build</para>
- <para>You can create a so-called <emphasis>developer build</emphasis> of the Staff
- Client by substituting <option>devbuild</option> for <option>build</option> when
- running <command>make</command>. The build will contain an extra configuration
- file that enables some developer options.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, run
- <command>make</command> from the Staff Client source directory:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make devbuild</userinput>
- </screen>
- </listitem>
- <listitem>
- <para>Compressed Javascript</para>
- <para>You can execute the Google <systemitem class="resource">Closure
- Compiler</systemitem> utility to automatically review and compress Javascript code
- after the build process completes, by substituting
- <option>compress-javascript</option> for "build" when running
- <command>make</command>. For more information see
- <ulink url="http://code.google.com/closure/compiler/">Google Closure Compiler</ulink>.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the
- following commands from the Staff Client source directory:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make compress-javascript</userinput>
- </screen>
- <para>You can also combine Javascript review and compression, and also perform a
- <emphasis>developer build</emphasis>.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the
- following commands from the Staff Client source directory:</para>
- <note>In the following <command>make</command> below, the order of options is
- important!</note>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make devbuild compress-javascript</userinput>
- </screen>
- </listitem>
- <listitem>
- <para>Automatic Update Host</para>
- <para>The host used to check for automatic Staff Client updates can be overridden
- by specifying the <option>AUTOUPDATE_HOST</option> option. The following commands
- could have been used during the normal build process:</para>
- <screen>
- <prompt># as the root user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>make AUTOUPDATE_HOST=localhost install</userinput>
- </screen>
- <para>You can manually set <option>AUTOUPDATE_HOST</option> to set up automatic
- update checking. The following commands will manually build the Staff Client using
- a different <option>AUTOUPDATE_HOST</option>.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change
- directory to the Staff Client source directory, then set the variable and build
- the Staff Client:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make AUTOUPDATE_HOST=localhost build</userinput>
- </screen>
- <para>For more information on Automatic Updates, see
- <xref linkend="staffclientinstallation-autoupdate"/>.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Installing and Activating a Manually Built Staff Client</title>
- <para>The Staff Client is automatically built, installed and activated as part of the normal
- <command>make <option>install</option></command> process for Evergreen server-side
- software. However, if you manually build the Staff Client, then you need to take additional steps
- to properly install and activate it. You also have the option of installing the Staff Client on
- the same machine it was built on, or on a different machine.</para>
- <para>Assuming you have already built the Staff Client, and that your installation is in the
- directory <filename class="directory">/openils/var/web/xul</filename>, as the
- <systemitem class="username">opensrf</systemitem> user, change directory to the
- Staff Client source directory, then execute the following commands:</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user
+ execute the following commands:</para>
<screen>
<prompt># as the opensrf user</prompt>
<userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>mkdir -p "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
- <userinput>cp -R build/server "/openils/var/web/xul/$(cat build/BUILD_ID)"</userinput>
+ <userinput>make win-client</userinput>
</screen>
- </section>
- <section>
- <title>Packaging the Staff Client</title>
- <para>Once the Staff Client has been built, you can create several forms of client packages by
- using some targetted <command>make</command> commands in the Staff Client source directory.</para>
+ <para>The output file <filename>evergreen_staff_client_setup.exe</filename> will be created.</para>
+ </simplesect>
+ <simplesect>
+ <title>Packaging a Linux Client</title>
+ <para>This build creates a Staff Client packaged as a compressed
+ <literal>tar</literal> archive file with <application>XULrunner</application>
+ already bundled with it. It requires that you already have the
+ <application>bzip2</application> utility installed on your system.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make linux-client</userinput>
+ </screen>
+ <para>The output file <filename>evergreen_staff_client.tar.bz2</filename> will be created.</para>
+ </simplesect>
+ <simplesect>
+ <title>Packaging a <application>Firefox</application> Extension</title>
+ <para>This build creates a Staff Client packaged as a <application>Firefox</application>
+ extension. It requires that you already have the <systemitem>zip</systemitem>
+ utility installed on your system.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make extension</userinput>
+ </screen>
+ <para>The output file <filename>evergreen.xpi</filename> will be created.</para>
+ </simplesect>
+ </section>
+ <section xml:id="staffclientinstallation-autoupdate">
+ <title>Staff Client Automatic Updates</title>
+ <indexterm>
+ <primary>staff client</primary>
+ <secondary>automatic updates</secondary>
+ </indexterm>
+ <para>It is possible to set up support for automatic Staff Client updates, either during
+ the normal Evergreen server-side build process, or by manually building the Staff Client
+ with certain special options.</para>
+ <warning>
+ <para>Automatic update server certificate requirements are more strict than
+ normal server requirements. <application>Firefox</application> and
+ <application>XULrunner</application> will both ignore any automatic update
+ server that is not validated by a trusted certificate authority. Servers with
+ exceptions added to force the Staff Client to accept them <emphasis>WILL NOT
+ WORK</emphasis>.</para>
+ <para>In addition, automatic updates have special requirements for the file
+ <filename>update.rdf</filename>:</para>
+ <orderedlist>
+ <listitem>It must be served from an SSL server, or</listitem>
+ <listitem>It must be signed with the <ulink url="https://developer.mozilla.org/en/McCoy">
+ https://developer.mozilla.org/en/McCoy</ulink> tool.</listitem>
+ </orderedlist>
+ <para>You can pre-install the signing key into the file
+ <filename>install.rdf</filename> directly, or install it into a copy as
+ <filename>install.mccoy.rdf</filename>. If the latter exists it will be copied
+ into the build instead of the original file
+ <filename>install.rdf</filename>.</para>
+ </warning>
+ <simplesect>
+ <title>Autoupdate Host</title>
+ <para>You can manually set the name of the automatic update host. If you do
+ not set the name then, by default, the Staff Client will not include an
+ automatic update preference. You can set the autoupdate host name as
+ follows:</para>
<itemizedlist>
<listitem>
- <para>Packaging a Generic Client</para>
- <para>This build creates a Staff Client packaged as an XPI file to use with
- <application>xulrunner</application>. It requires that you already have the
- <systemitem>zip</systemitem> utility installed on your system. It will create the
- output file <filename>evergreen_staff_client.xpi</filename>, suitable for use with
- the <application>xulrunner</application> parameter
- <option>--install-app</option>>.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change
- directory to the Staff Client source directory, then execute the following
- commands:</para>
+ <para>At configuration time during the normal <emphasis>make install</emphasis>
+ process for Evergreen server-side software.</para>
+ <para>You can do this when you first configure the Evergreen server-side
+ software (see <xref linkend="serversideinstallation-configure"/>).
+ As the <systemitem class="username">opensrf</systemitem> user, execute
+ the following commands:</para>
<screen>
<prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make generic-client</userinput>
- </screen>
- </listitem>
- <listitem>
- <para>Packaging a Windows Client</para>
- <para>This build creates a Staff Client packaged as a Windows executable. It
- requires that you already have the "unzip" utility installed on your system. It
- also requires that you install <ulink url="http://nsis.sourceforge.net/">NSIS
- (Nullsoft Scriptable Install System)</ulink>, a professional open source utility
- package used to create Windows installers (the "makensis" utility is installed as
- part of the "nsis" package). We recommend using Version 2.45 or later. This build
- will create the output file "evergreen_staff_client_setup.exe".</para>
- <para>If you wish for the Staff Client to have a link icon/tray icon by default,
- you may wish to provide a pre-modified <application>xulrunner-stub.exe</application>.
- Place it in the Staff Client source directory and <command>make</command> will
- automatically use it instead of the one that comes with the downloaded
- <application>XULRunner</application> release. The version of
- <application>xulrunner-stub.exe</application> need not match exactly.</para>
- <para>You can also use a tool such as
- <ulink url="http://www.angusj.com/resourcehacker/">Resource Hacker</ulink> to
- embed icons. Resource Hacker is an open-source utility used to view, modify,
- rename, add, delete and extract resources in 32bit Windows executables.
- See the following table for some useful icon ID strings:</para>
- <table>
- <title>Useful icon ID strings</title>
- <tgroup align="left" cols="2" colsep="1" rowsep="1">
- <colspec colnum="1" colwidth="1.0*"/>
- <colspec colnum="2" colwidth="1.0*"/>
- <tbody>
- <row>
- <entry>IDI_APPICON</entry>
- <entry>Tray icon</entry>
- </row>
- <row>
- <entry>32512</entry>
- <entry>Default window icon</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change
- directory to the Staff Client source directory, then execute the following
- commands:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make win-client</userinput>
- </screen>
- </listitem>
- <listitem>
- <para>Packaging a Linux Client</para>
- <para>This build creates a Staff Client package for Linux as a "tar.bz2" file with
- <application>XULRunner</application> already bundled with it. It creates the
- output file "evergreen_staff_client.tar.bz2".</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change
- directory to the Staff Client source directory, then execute the following
- commands:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make linux-client</userinput>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname</userinput>
+ <userinput>make</userinput>
</screen>
</listitem>
<listitem>
- <para>Packaging a Firefox Extension</para>
- <para>This build requires that you already have the <systemitem>zip</systemitem>
- utility installed on your system. It creates a Staff Client packaged as a Firefox
- extension and creates the output file <filename>evergreen.xpi</filename>.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change
- directory to the Staff Client source directory, then execute the following
- commands:</para>
+ <para>During a manual Staff Client build process.</para>
+ <para>You can override the variable
+ <envar>AUTOUPDATE_HOST=hostname</envar> and manually build the
+ Staff Client from the <literal>staff_client</literal>
+ directory (see <xref linkend="staffclientinstallation-autoupdatehost"/>
+ for details). If you specify only a bare hostname (for example,
+ <systemitem class="domainname">example.com</systemitem>) then
+ the Staff Client will automatically use the secure URL
+ <systemitem class="domainname">https://example.com</systemitem>.
+ If you wish to use a non-https URL, then you must explicitly
+ specify the full URL (for example,
+ <systemitem class="domainname">http://example.com</systemitem>).</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands to build the Staff Client (remember to
+ replace <literal>SOME_URL</literal> with an appropriate value)
+ :</para>
<screen>
<prompt># as the opensrf user</prompt>
<userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make extension</userinput>
+ <userinput>make AUTOUPDATE_HOST=http://SOME_URL build</userinput>
</screen>
</listitem>
</itemizedlist>
- </section>
- <section xml:id="staffclientinstallation-autoupdate">
- <title>Staff Client Automatic Updates</title>
+ </simplesect>
+ <simplesect>
+ <title>Building Updates</title>
<indexterm>
<primary>staff client</primary>
<secondary>automatic updates</secondary>
+ <tertiary>building</tertiary>
</indexterm>
- <para>It is possible to set up support for automatic Staff Client updates, either during the
- normal Evergreen server-side build process, or by manually building the Staff Client with certain
- special options.</para>
- <caution>
- <para>Automatic update server certificate requirements are more strict than normal
- server requirements. Firefox and <application>XULRunner</application> will both ignore
- any automatic update server that is not validated by a trusted certificate authority.
- Servers with exceptions added to force the Staff Client to accept them
- <emphasis>WILL NOT WORK</emphasis>.</para>
- <para>In addition, automatic updates have special requirements for the file
- <filename>update.rdf</filename>:</para>
- <orderedlist>
- <listitem>It must be served from an SSL server, or</listitem>
- <listitem>It must be signed with the
- <ulink url="https://developer.mozilla.org/en/McCoy">McCoy</ulink> tool.</listitem>
- </orderedlist>
- <para>You can pre-install the signing key into the file <filename>install.rdf</filename>
- directly, or install it into a copy as <filename>install.mccoy.rdf</filename>. If the
- latter exists it will be copied into the build instead of the original file
- <filename>install.rdf</filename>.</para>
- </caution>
- <simplesect>
- <title>Autoupdate Host</title>
- <para>The name of the automatic update host can be provided in either of two ways:</para>
- <orderedlist>
- <listitem>At configuration time for the normal build of the Evergreen server-side
- software, or</listitem>
- <listitem>During a manual Staff Client build process.</listitem>
- </orderedlist>
- <para/>
- <itemizedlist>
- <listitem>
- <para>At configuration time for the normal build of Evergreen server-side
- software</para>
- <para>This must be done when the Evergreen server-side software is first
- configured (see <xref linkend="serversideinstallation-configure"/>). As
- the <systemitem class="username">opensrf</systemitem> user, use the
- utility "configure" as shown:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf --with-updateshost=hostname</userinput>
- <userinput>make</userinput>
- </screen>
- </listitem>
- <listitem>
- <para>During a manual Staff Client build process</para>
- <para>You will used the variable AUTOUPDATE_HOST=hostname (see above).
- If you specify just a hostname (such as
- <systemitem class="domainname">example.com</systemitem>) then
- the URL will be a secure URL (such as
- <systemitem class="domainname">https://example.com</systemitem>.
- If you wish to use a non-HTTPS URL then prefix the hostname with
- <systemitem class="domainname">http://</systemitem> (such as
- <systemitem class="domainname">http://example.com</systemitem>).</para>
- <para>If neither option is used then, by default, the Staff Client will
- not include the automatic update preferences.</para>
- </listitem>
- </itemizedlist>
- </simplesect>
- <simplesect>
- <title>Building Updates</title>
- <indexterm>
- <primary>staff client</primary>
- <secondary>automatic updates</secondary>
- <tertiary>building</tertiary>
- </indexterm>
- <para>Similar to building clients, the targets <option>generic-updates</option>,
- <option>win-updates</option>, <option>linux-updates</option>, and
- <option>extension-updates</option> can be used individually with <command>make</command>
- to build the update files for the Staff Client. To build all the targets at once, simply
- use the target <option>updates</option>.</para>
- <para>A full update will be built for each specified target (or for all if you use the
- target <option>updates</option>). For all but extensions any previous full updates
- (archived by default in the directory
- <filename class="directory">/openils/var/updates/archives</filename>) 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 currentlysupport partial updates.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to
- the Staff Client source directory, then execute the following commands:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- </screen>
- <para>Command to build all updates at once:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>make updates</userinput>
- </screen>
- <para>commands to build updates individually:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>make generic-updates</userinput>
- <userinput>make win-updates</userinput>
- <userinput>make linux-updates</userinput>
- <userinput>make extension-updates</userinput>
- </screen>
- </simplesect>
- <simplesect>
- <title>Building updates with clients</title>
- <indexterm>
- <primary>staff client</primary>
- <secondary>automatic updates</secondary>
- <tertiary>building with clients</tertiary>
- </indexterm>
- <para>To save time and effort you can build updates and manual download clients at the
- same time by adding <option>-client</option> to each target name. For instance, you can
- specify <option>win-updates-client</option>. You can also specify
- <option>updates-client</option> to build all the targets at once. This does not work for
- <option>extension-updates</option>.</para>
- <para>The clients will be installed alongside the updates and listed on the
- <filename>manualupdate.html</filename> page, rather than left in the Staff Client
- directory.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to
- the Staff Client source directory, then execute the following commands:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- </screen>
- <para>Command to build all updates at once:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>make updates-client</userinput>
- </screen>
- <para>Command to build updates individually:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>make generic-updates-client</userinput>
- <userinput>make win-updates-client</userinput>
- <userinput>make linux-updates-client</userinput>
- </screen>
- </simplesect>
- <simplesect>
- <title>Activating the Update Server</title>
- <indexterm>
- <primary>staff client</primary>
- <secondary>automatic updates</secondary>
- <tertiary>activating the update server</tertiary>
- </indexterm>
- <para>This section reviews scripts associated with the update server, and requires some
- final adjustments to file permissions.</para>
- <para>The Apache example configuration creates an "updates" directory that, by default,
- points to the directory <filename class="directory">/openils/var/updates/pub</filename>.
- This directory contains one HTML file and several specially-named script files.</para>
- <para>The <filename>updatedetails.html</filename> file is the fallback web page for the
- update details. The <filename>check</filename> script is used for
- <application>XULRunner</application> updates. The <filename>update.rdf</filename> script
- is used for extension updates. The <filename>manualupdate.html</filename> file 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).</para>
- <para>The following scripts should be marked as executable: <filename>check</filename>,
- <filename>download</filename>, <filename>manualupdate.html</filename>,
- <filename>update.rdf</filename>. Execute the following commands:</para>
- <screen>
- <prompt># as the root user</prompt>
- <userinput>cd /openils/var/updates/pub</userinput>
- <userinput>chmod +x check download manualupdate.html update.rdf</userinput>
- </screen>
- </simplesect>
- </section>
- <section>
- <title>Other tips</title>
- <simplesect>
- <title>Multiple workstations on one install</title>
- <para>Multiple workstation registrations for the same server can be accomplished with a
- single Staff Client install by using multiple profiles. When running
- <application>XULRunner</application> you can specify the option "-profilemanager" or "-P"
- (uppercase "P") to force the Profile Manager to start. Unchecking the "Don't ask at
- startup" option will make this the default.</para>
- <para>Once you have opened the Profile Manager you can create additional profiles, one for
- each workstation you wish to register. You may need to install SSL exceptions for each
- profile.</para>
- <para>When building targets <option>win-client</option>,
- <option>win-updates-client</option>, or <option>updates-client</option>, you can specify
- <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an <guimenuitem>Evergreen Staff Client
- Profile Manager</guimenuitem> option to the start menu.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change directory to
- the Staff Client source directory, then execute the following commands:</para>
- <screen>
- <prompt># as the opensrf user</prompt>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
- <userinput>make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput>
- </screen>
- </simplesect>
- <simplesect>
- <title> Multiple Staff Clients</title>
- <para>This may be confusing if you are not 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).</para>
- <para>Once you have created the profiles, run <application>XULRunner</application> with
- the option <option>-no-remote</option> (in addition to <option>-profilemanger</option> or
- <option>-P</option> if neeeded). Instead of <application>XULRunner</application> 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.</para>
- </simplesect>
- </section>
+ <para>Similar to building clients, you can use the targets
+ <option>generic-updates</option>, <option>win-updates</option>,
+ <option>linux-updates</option>, and <option>extension-updates</option>
+ individually with <command>make</command> to build the update files for the
+ Staff Client. To build all the targets at once, simply use the target
+ <option>updates</option>.</para>
+ <para>A full update will be built for each specified target (or for all if you
+ use the target <option>updates</option>). For all but extensions any previous
+ full updates (archived by default in the directory
+ <filename class="directory">/openils/var/updates/archives</filename>) 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 currently support
+ partial updates.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, change
+ directory to the Staff Client source directory, then execute the following
+ commands:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ </screen>
+ <para>Command to build all updates at once:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>make updates</userinput>
+ </screen>
+ <para>commands to build updates individually:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>make generic-updates</userinput>
+ <userinput>make win-updates</userinput>
+ <userinput>make linux-updates</userinput>
+ <userinput>make extension-updates</userinput>
+ </screen>
+ </simplesect>
+ <simplesect>
+ <title>Building updates with clients</title>
+ <indexterm>
+ <primary>staff client</primary>
+ <secondary>automatic updates</secondary>
+ <tertiary>building with clients</tertiary>
+ </indexterm>
+ <para>To save time and effort you can build updates and manual download
+ clients at the same time by adding the phrase <literal>"-client"</literal> to each
+ target name (for example, you could specify <option>updates-client</option> to build
+ all the targets at once, or you could specify <option>win-updates-client</option>
+ to build updates individually). This process will not work for the option
+ <option>extension-updates</option>.</para>
+ <para>The clients will be installed alongside the updates and listed on the
+ <filename>manualupdate.html</filename> page, instead of being left in the
+ <literal>staff_client</literal> directory.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, execute
+ one of the following commands:</para>
+ <para>To build all updates at once:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make updates-client</userinput>
+ </screen>
+ <para>To build updates individually:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make generic-updates-client</userinput>
+ <userinput>make win-updates-client</userinput>
+ <userinput>make linux-updates-client</userinput>
+ </screen>
+ </simplesect>
+ <simplesect>
+ <title>Activating the Update Server</title>
+ <indexterm>
+ <primary>staff client</primary>
+ <secondary>automatic updates</secondary>
+ <tertiary>activating the update server</tertiary>
+ </indexterm>
+ <para>This section reviews scripts associated with the update server, and
+ requires some final adjustments to file permissions.</para>
+ <para>The Apache example configuration creates an <literal>updates</literal>
+ directory that, by default, points to the directory
+ <filename class="directory">/openils/var/updates/pub</filename>. This
+ directory contains one HTML file and several specially-named script files.</para>
+ <para>The <filename>updatedetails.html</filename> file is the fallback web
+ page for the update details. The <filename>check</filename> script is used for
+ <application>XULrunner</application> updates. The
+ <filename>update.rdf</filename> script is used for extension updates.
+ The <filename>manualupdate.html</filename> file 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
+ <application>Firefox</application> trying to install it as an
+ extension).</para>
+ <para>To change the permissions for the scripts
+ <filename>check</filename>, <filename>download</filename>,
+ <filename>manualupdate.html</filename>, and
+ <filename>update.rdf</filename>, as the root user execute the following
+ commands:</para>
+ <screen>
+ <prompt># as the root user</prompt>
+ <userinput>cd /openils/var/updates/pub</userinput>
+ <userinput>chmod +x check download manualupdate.html update.rdf</userinput>
+ </screen>
+ </simplesect>
+ </section>
+ <section>
+ <title>Other tips</title>
+ <simplesect xml:id="staffclientinstallation-othertips">
+ <title>Multiple workstations on one install</title>
+ <para>Multiple workstation registrations for the same server can be accomplished
+ with a single Staff Client install by using multiple profiles. When running
+ <application>XULrunner</application> you can specify the option
+ <literal>"-profilemanager"</literal> or <literal>"-P"</literal> (uppercase "P")
+ to force the Profile Manager to start. Unchecking the <literal>"Don't ask at startup"</literal>
+ option will make this the default.</para>
+ <para>Once you have opened the Profile Manager you can create additional
+ profiles, one for each workstation you wish to register. You may need to install
+ SSL exceptions for each profile.</para>
+ <para>When building any of the targets <option>win-client</option>,
+ <option>win-updates-client</option>, or <option>updates-client</option>, you can
+ specify <option>NSIS_EXTRAOPTS=-DPROFILES</option> to add an option
+ <guimenuitem>"Evergreen Staff Client Profile Manager"</guimenuitem> to the
+ start menu.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands:</para>
+ <screen>
+ <prompt># as the opensrf user</prompt>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client</userinput>
+ <userinput>make NSIS_EXTRAOPTS=-DPROFILES win-client</userinput>
+ </screen>
+ </simplesect>
+ <simplesect>
+ <title> Multiple Staff Clients</title>
+ <para>It may be confusing if you are not 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 the previous
+ tip in <xref linkend="staffclientinstallation-othertips"/>).</para>
+ <para>Once you have created the profiles, run
+ <application>XULrunner</application> with the option <option>-no-remote</option>
+ (in addition to <option>"-profilemanger"</option> or <option>"-P"</option> if
+ neeeded). Instead of <application>XULrunner</application> 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.</para>
+ </simplesect>
</section>
</section>
<section xml:id="staffclientinstallation-running-staffclient">
<secondary>running</secondary>
<tertiary>linux</tertiary>
</indexterm>
- <para>Run the Staff Client on a Linux system by using the application
- <application>XULRunner</application> (installed automatically and by default with Firefox version 3.0
- and later on Ubuntu and Debian distributions).</para>
- <para>For example, if the source files for the Evergreen installation are in the directory
- <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/</filename>, start the Staff
- Client as shown in the following example:</para>
+ <para>You can run the Staff Client on a Linux system by using the
+ <application>XULrunner</application> application (installed automatically and by default
+ with <application>Firefox</application> <literal>Version 3.0</literal> and later on
+ <systemitem class="osname">Ubuntu</systemitem> and
+ <systemitem class="osname">Debian</systemitem> distributions).</para>
+ <para>For example, if the source files for the Evergreen installation are in the directory
+ <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/</filename> you can start the
+ Staff Client as shown in the following example:</para>
<screen>
<prompt># as the opensrf user</prompt>
- <userinput>xulrunner /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build/application.ini</userinput>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build</userinput>
+ <userinput>xulrunner application.ini</userinput>
</screen>
- <simplesect xml:id="staffclientinstallation-proxy">
- <title>Running the Staff Client over an SSH Tunnel</title>
+ <section xml:id="staffclientinstallation-workstationnames">
+ <title>Assigning Workstation Names</title>
+ <indexterm>
+ <primary>staff client</primary>
+ <secondary>assigning workstation names</secondary>
+ </indexterm>
+ <para>The Staff Client must be assigned to a library and given a unique name before it
+ will connect fully to the Evergreen server. The only restriction is that the workstation's
+ name must be unique within the assigned library. Make sure to select a workstation name
+ that you will remember later, and reflects the role, purpose, and/or location of a
+ particular computer. These names will come up later in statistical reporting, and can also
+ be handy when troubleshooting.</para>
+ <mediaobject>
+ <alt>
+ <phrase>Example of unconfigured Staff Client</phrase>
+ </alt>
+ <imageobject>
+ <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-1.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ <para>In order to assign a workstation a name, a user with appropriate
+ permissions must login to the Staff Client. In PINES, the local system
+ administrator (OPSM) has the ability to assign workstation names in their
+ library system. Library managers (LIBM's) have the ability within their
+ branch. To assign a workstation a name, login to the system. You will be
+ prompted to assign the workstation a library and a name:</para>
+ <mediaobject>
+ <alt>
+ <phrase>Example of configured Staff Client</phrase>
+ </alt>
+ <imageobject>
+ <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-2.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ <para>Select the library this workstation physically operates in from the drop
+ down menu. In this example, we have selected "MGRL-MA". Type in a friendly name
+ for the workstation. In this example, we are installing the Staff Client on the
+ director's personal system, and have named it as such. Then click
+ <guibutton>'Register'</guibutton>.</para>
+ <para>Once you have registered your workstation
+ with the server, your screen will look like this:</para>
+ <mediaobject>
+ <alt>
+ <phrase>Example of registered Staff Client</phrase>
+ </alt>
+ <imageobject>
+ <imagedata fileref="../media/staffclientinstallation-staffclient-workstationnames-3.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ <para>You are now ready to log into the Staff Client for the first time. Type in
+ your password again, and click <guibutton>'Login'</guibutton>.</para>
+ </section>
+ <section xml:id="staffclientinstallation-proxy">
+ <title>Running the Staff Client Over An <systemitem class="protocal">SSH</systemitem> Tunnel</title>
<indexterm>
<primary>staff client</primary>
<secondary>running through an SSH tunnel</secondary>
</indexterm>
- <para>The Staff Client can use an SSH tunnel as a SOCKS 5 proxy.</para>
+ <para>The Staff Client can use an <systemitem class="protocal">SSH</systemitem>
+ tunnel as a <systemitem class="protocal">SOCKS 5</systemitem> proxy.</para>
<simplesect>
<title>Configuring a Proxy for the Staff Client</title>
- <para>There are several reasons for sending network traffic for the Staff Client through an SSH
- proxy:</para>
+ <para>There are several reasons for sending network traffic for the Staff Client through
+ an <systemitem class="protocal">SSH</systemitem> proxy:</para>
<itemizedlist>
<listitem>
<para>Firewalls may prevent you from reaching the server. This may happen when you
</itemizedlist>
</simplesect>
<simplesect>
- <title>Setting Up an SSH Tunnel</title>
- <para>You will need a server that allows you to log in via SSH and has network access to
- the Evergreen server you want to reach. You will use your username and password for that
+ <title>Setting Up an <systemitem class="protocal">SSH</systemitem> Tunnel</title>
+ <para>You will need a server that allows you to log in via <systemitem class="protocal">SSH</systemitem> and has network access to the Evergreen server
+ you want to reach. You will use your username and password for that
<systemitem class="protocal">SSH</systemitem> server to set up a tunnel.</para>
- <para>For Windows users, one good solution is the open-source utility
- <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>, a free
- <systemitem class="protocal">telnet/SSH</systemitem> client. When setting up a PuTTY
- session:</para>
+ <para>For <systemitem class="osname">Windows</systemitem> users, one good solution
+ is the open-source utility
+ <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</ulink>
+ a free <systemitem class="protocal">telnet/SSH</systemitem> client. When setting
+ up a <application>PuTTY</application> session:</para>
<mediaobject>
<alt>
- <phrase>Setting up an SSH tunnel in PuTTY</phrase>
+ <phrase>Setting up an <systemitem class="protocal">SSH</systemitem>
+ tunnel in <application>PuTTY</application></phrase>
</alt>
<imageobject>
<imagedata fileref="../media/staffclientinstallation-proxy-putty.png" format="PNG" scalefit="1" width="70%"/>
<title>Configuring the Staff Client to Use the <systemitem class="protocal">SSH</systemitem> Tunnel</title>
<para>In order to tell the Staff Client that all traffic should be sent through the
<systemitem class="protocal">SSH</systemitem> tunnel just configured, you must edit the
- file <filename>C:\Program Files\Evergreen Staff
- Client\greprefs\all.js</filename>. Search this file for the word
- <literal>socks</literal> to find the appropriate section for the following
- changes.</para>
+ file <filename>C:\Program Files\Evergreen Staff Client\greprefs\all.js</filename>.
+ Search this file for the word <literal>socks</literal> to find the appropriate section
+ for the following changes.</para>
<mediaobject>
<alt>
<phrase>The SOCKS section of "all.js" before changes</phrase>
<imagedata fileref="../media/staffclientinstallation-proxy-socks-2.png" format="PNG" scalefit="1" width="70%"/>
</imageobject>
</mediaobject>
- <para>If everything is working correctly, you should now be able to run the Staff Client and all
- its data will be sent encrypted through the <systemitem class="protocal">SSH</systemitem> tunnel
- you have just configured.</para>
+ <para>If everything is working correctly, you should now be able to run the Staff Client
+ and all its data will be sent encrypted through the
+ <systemitem class="protocal">SSH</systemitem> tunnel you have just configured.</para>
</simplesect>
- </simplesect>
+ </section>
</section>
</chapter>
projects / Evergreen-DocBook.git / commitdiff