Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Previous revision
dev:client_coding:building_the_standalone_client [2017/12/18 09:07]
dev:client_coding:building_the_standalone_client [2018/04/27 00:14] (current)
rmzelle Update CSL style MIME type
Line 1: Line 1:
 +====== 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 [[building_the_standalone_client_windows_notes|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: <code sh>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</​code>​
 +  - Change to the source code repo and install Node.js modules using Node 8 or later: <code sh>cd zotero-client
 +npm i</​code>​
 +  - Run the JS build process (Babel, etc.): <code sh>npm run build</​code>​ This will compile source files into a ''​build/''​ directory. You can also run ''​npm start''​ to automatically rebuild as you change files, but it may be simpler to run ''​npm run build''​ in a single line with ''​dir_build''​ below.
 +  - Change to the zotero-standalone-build directory and check your system for the necessary tools: <code sh>cd ../​zotero-standalone-build
 +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.
 +  - Download the Firefox runtime and PDF tools 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.\\ \\ **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: <code sh>
 +./​fetch_pdftools
 +</​code>​
 +  - Build Zotero: <code sh>​scripts/​dir_build</​code>​ 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''​. For rapid iteration, we recommend combining these commands into a separate script. (We plan to optimize this process in the future.)
 +
 +You can pass ''​-ZoteroDebugText''​ or ''​-ZoteroDebug''​ to the executable for real-time debug output, 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 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.
 +
 +==== Helper Script ====
 +
 +The [[https://​raw.githubusercontent.com/​zotero/​zotero-standalone-build/​master/​scripts/​build_and_run|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 =====
 +
 +Zotero can run Firefox extensions as plugins. You can run Firefox extensions from source code in Zotero the same way you could in Firefox. Create an ''​extensions''​ directory in the [[kb:​profile_directory|Zotero profile directory]] and create a file named after the id in the extension'​s install.rdf (e.g. ''​zotplugin@example.com''​) containing the path to the extension source code. The extension will then be automatically installed when you start Zotero.
 +===== 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.
 +  - 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 |