====== Building the Standalone Client ======

**Note:** The instructions below are not aimed for general use by the everyday user of Zotero. Some of the information below may need to be updated to work with the current code. Please update the instructions as necessary.

===== Build Steps ====

//Note: The following commands assume a POSIX-compliant system. On Windows, first install [[https://www.cygwin.com/|Cygwin]], install Git through Cygwin, and then run the following commands in the Cygwin terminal.//

Zotero Standalone is currently built from an XPI of Zotero for Firefox. An included helper script, ''scripts/dir_build'', can automate the process of creating a Standalone build from an unpacked local Zotero git repository.

  - To build from the Zotero source code, you'll need the Zotero source code and the ''zotero-build'' repository: <code sh>git clone --recursive https://github.com/zotero/zotero
git clone --recursive https://github.com/zotero/zotero-build</code> (If you just want to create a build from an existing XPI — for example, one you've extracted, modified, and recompressed — you can skip this step, though building from a local Zotero git repository is generally easier. If you want to build directly from a given commit of the Zotero source without modifications, you can skip ''zotero/zotero''.)
  - Clone the ''zotero-standalone-build'' repo and change to that directory: <code sh>git clone --recursive https://github.com/zotero/zotero-standalone-build
cd zotero-standalone-build
</code>
  - Check your system for the necessary tools: <code sh>scripts/check_requirements</code>This script checks all requirements for the official Zotero distribution system. If you're only creating a custom build, you only need the build requirements listed at the top, not the distribution requirements.
  - Run ''fetch_xulrunner.sh'' for the desired platform(s) (''m''=Mac, ''w''=Windows, ''l''=Linux): <code sh>
./fetch_xulrunner.sh -p m
</code>This will download Firefox runtime files to the ''xulrunner/'' subdirectory and modify them for use with Zotero Standalone.\\ \\ **Note:** Due to the way Firefox is packaged, fetch_xulrunner.sh can only retrieve Mac builds on macOS.
  - Build Zotero Standalone, using one of three methods:
    - To build from a given branch/tag/commit of the Zotero source, first build an XPI using ''build_xpi'' (or ''build_xpi_4.0'' for the ''4.0'' branch). To see available options:<code sh>../zotero-build/xpi/build_xpi --help
../zotero-build/xpi/build_xpi_4.0</code> Then follow the instructions in II.
    - To build from an XPI, run ''build.sh'' directly for the desired platform(s): <code sh>./build.sh -f /path/to/zotero.xpi -p m -d</code>
    - To build for the current platform from the Zotero git repository you cloned to ''../zotero'' (using the current branch and code), use the ''dir_build'' helper script: <code sh>scripts/dir_build</code>

Your desired builds should now be available in the ''staging/'' subdirectory in unpackaged form.

Distribution steps are beyond the scope of this page, but see ''scripts/build_and_deploy'' for an example of the necessary steps.

===== Packaging on Windows =====

==== Prerequisites == 

  * Build requirements as indicated by ''scripts/check_requirements''
  * [[http://www.scratchpaper.com/|Unicode NSIS]] and install the following (Unicode!) plugins by copying the .dll files to ''NSIS\Unicode\Plugins'' folder
    * [[https://github.com/mozilla/gecko-dev/tree/master/other-licenses/nsis/Plugins|AppAssocReg, ApplicationID, InvokeShellVerb, ShellLink, and UAC]]
    * To install all at once, ''cd'' to the plugins folder and run the following commands: <code sh>wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/AppAssocReg.dll
wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/ApplicationID.dll
wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/InvokeShellVerb.dll
wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/ShellLink.dll
wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/UAC.dll</code>
  * The [[http://www.microsoft.com/en-us/download/details.aspx?id=8279|Windows SDK]] is needed for the included signtool.exe utility. Only the main Windows SDK component is required. If you experience errors with the installer, [[http://stackoverflow.com/questions/19366006/error-when-installing-windows-sdk-7-1|try uninstalling Microsoft Visual C++ 2010 Redistributable from your computer first]].

==== Building ====

  - Verify that git is set to check out files without modifying line endings.<code>
$ git config --global core.autocrlf

</code>The response should be either empty (meaning ''false'') or ''input''. If set to ''true'' (as it may be if you selected the default option while installing the Windows version of git), change this with the following command:<code>
git config --global core.autocrlf false
</code>See the [[http://git-scm.com/docs/git-config|git manual]] for details on this setting.
  - After checking out the ''zotero-standalone-build'' repository as explained above, adjust the paths in config.sh to point to the correct executables of NSIS and the Windows SDK. You might want to set SIGN=1 to 0, to stop getting error messages
  - Follow the build steps from the previous section, but omit the ''-d'' flag when calling ''build.sh'' to create the installer package.

===== Installation and Packaging Notes =====

**Note:** These instructions are not applicable on OS X, which handles protocol handler and MIME type registration through the bundled Info.plist file. Additionally, they are only applicable on Windows if, for some ungodly reason, you want to install Zotero Standalone without running the installer.

=== Protocol handler registration ===
Zotero Standalone should be registered as the system's default protocol handler for the ''zotero:%%//%%'' protocol. This is necessary to make clicking the Zotero button in Firefox open Zotero Standalone when both are running simultaneously.

=== File extensions and MIME types ===
Zotero should be registered as a handler for the following file extensions and MIME types:
^ File type description ^ File extension(s) ^ MIME type(s) ^
| Research Information Systems Document | ris | application/x-research-info-systems\\ application/x-endnote-refer\\ text/x-research-info-systems\\  text/application/x-research-info-systems \\ text/ris\\  ris |
| ISI Common Export Format Document | ciw, isi | application/x-inst-for-Scientific-info |
| Metadata Object Description Schema Document | mods | application/mods+xml |
| Resource Description Framework Document | rdf | application/rdf+xml |
| BibTeX Document | bib, bibtex | application/x-bibtex\\ text/x-bibtex |
| MARC Record | mrc, marc | application/marc |
| CSL Citation Style | csl | text/x-csl |