Building the Zotero Client
Build Steps
Note: The following commands assume a POSIX-compliant system. On Windows the initial steps are different, so please follow the Windows-specific steps first.
For historical reasons, several separate build processes are currently required to build the Zotero client. An included helper script, dir_build
, can automate the process of creating a client build from an unpacked local Zotero git repository. We plan to optimize the build process further after Zotero 4.0 is discontinued.
- Clone the Zotero source code, Zotero XPI build scripts, and standalone client build scripts:
git clone --recursive https://github.com/zotero/zotero zotero-client git clone --recursive https://github.com/zotero/zotero-build git clone --recursive https://github.com/zotero/zotero-standalone-build
- Change to the source code repo and install Node.js modules using Node 8 or later:
cd zotero-client npm i
- Run the JS build process (Babel, etc.):
npm run build
This will compile source files into a
build/
directory. You can also runnpm start
to automatically rebuild as you change files, but it may be simpler to runnpm run build
in a single line withdir_build
below. - Change to the zotero-standalone-build directory and check your system for the necessary tools:
cd ../zotero-standalone-build scripts/check_requirements
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.
- Download the Firefox runtime and PDF tools for the desired platform(s) (
m
=Mac,w
=Windows,l
=Linux):./fetch_xulrunner.sh -p m
This will download Firefox runtime files to the
xulrunner/
subdirectory and modify them for use with Zotero.
Note: Due to the way Firefox is packaged,fetch_xulrunner.sh
can retrieve Mac builds only on macOS. - Download the modified Poppler PDF tools that are bundled with Zotero:
./fetch_pdftools
- Build Zotero:
scripts/dir_build
This creates a build for the current platform from the Zotero git repository you cloned to
../zotero-client
(using the current branch and code). You can pass-p
to create a build for another platform.
Your desired build 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.
Running Your Custom Build
After you've built the client, you can run it via the GUI or from the command line:
Mac
staging/Zotero.app/Contents/MacOS/zotero
Linux
staging/Zotero_linux-x86_64/zotero
Windows
staging/Zotero_win32/zotero.exe
Command-line Flags
You'll need to rebuild the client each time you make code changes by running npm run build
in zotero-client
followed by scripts/dir_build
in zotero-standalone-build
. In most cases, you'll want to use the helper script below.
You can pass -ZoteroDebugText
or -ZoteroDebug
to the executable for real-time debug output from Zotero.debug()
, and -jsconsole
to open the Error Console. If you're working on something that doesn't require styles or translators, the -ZoteroSkipBundledFiles
flag can speed up startup time after rebuilding.
A -debugger
flag will run the Mozilla DevTools server, which you can connect to from the Firefox 60 ESR DevTools by using the “Connect…” option and pointing to port 6100. You'll first need to enable browser chrome/add-on and remote debugging in the settings (gear icon) pane of the Firefox Web Console and pass -t
to the dir_build
script. (Be sure to use Firefox 60 ESR in a separate Firefox profile and disable automatic updates to avoid being updated to a newer ESR.) This flag is also available in pre-built beta builds.
Helper Script
The build_and_run script can automate some of the above steps. Copy the script somewhere in your path with a name of your choosing and then use it to quickly start a dev build of Zotero from the staging directory, optionally rebuilding first.
Options:
-r Rebuild (calling `npm run build` automatically if `npm start` isn't running)
-b Skip bundled styles and translators
-d Start devtools server on port 6100
Running Zotero Plugins
Packaging
Mac
- In Keychain Access, create
build
keychain with password - Import Developer ID certificate, public key, and private key
- Set up app-specific password for Apple developer account
- Create a
config-custom.sh
file:SIGN=1 KEYCHAIN=build KEYCHAIN_PASSWORD=<keychain password> NOTARIZATION_BUNDLE_ID=<bundle id (e.g., org.foo.App) — only used for notification emails> NOTARIZATION_USER="<username of Apple developer account>" NOTARIZATION_PASSWORD="<app-specific password for Apple developer account>" BUILD_PLATFORMS=m
Windows
Prerequisites
- Build requirements as indicated by
scripts/check_requirements
- Unicode NSIS 2.46.5 and install the following (Unicode!) plugins by copying the .dll files to
NSIS\Unicode\Plugins
folder- To install all at once,
cd
to the plugins folder and run the following commands: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
- The 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, 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.
$ git config --global core.autocrlf
The response should be either empty (meaning
false
) orinput
. If set totrue
(as it may be if you selected the default option while installing the Windows version of git), change this with the following command:git config --global core.autocrlf false
See the 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. - See
scripts/dir_build
for the individual commands to run. Omit the-s
flag when calling./build.sh
to create the installer package.
Installation and Packaging Notes
Note: These instructions are not applicable on macOS, which handles protocol handler and MIME type registration through the bundled Info.plist file. Additionally, they are only applicable on Windows if for some reason you want to run Zotero without running the installer.
Protocol handler registration
Zotero should be registered as the system's default protocol handler for the zotero://
protocol.
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 | vnd.citationstyles.style+xml |