Skip to content

installing-from-source.rst

Latest commit

 

History

History
126 lines (73 loc) · 4.52 KB

installing-from-source.rst

File metadata and controls

126 lines (73 loc) · 4.52 KB

Installing from source

Here's the guide to installing ActivityWatch from source. If you are just looking to try it out, see the getting started guide instead.

Note

This is written for Linux and macOS. For Windows the build process is more complicated and we therefore suggest using the pre-built packages instead on that operating system (but if you really have to, see :doc:`this guide <installing-from-source-on-windows>`).

Cloning the submodules

Since the ActivityWatch bundlerepo uses submodules, you first need to clone the submodules.

This can either be done at the cloning stage with:

git clone --recursive https://github.com/ActivityWatch/activitywatch.git

Or afterwards (if you've already cloned normally) using:

git submodule update --init --recursive

Checking dependencies

You need:

  • Python 3.6 or later, check with python3 -V (required to build the core components)
  • Node 8 or higher, check with node -v and npm -v (required to build the web UI)

Using a virtualenv

Note

If you don't want to use a virtualenv you could instead set the environment variable PIP_USER=true when building in the next step. But make sure that the folder ~/.local/bin (on Linux) or ~/Library/Python/<version>/bin (on macOS) is in your PATH.

It is recommended to use a virtualenv in order to avoid polluting your system with ActivityWatch-specific Python packages. It also makes it easier to uninstall since all you have to do is remove the virtualenv folder.

python3 -m venv venv

Now activate the virtualenv in your current shell session:

# For bash/zsh users:
source ./venv/bin/activate
# For Windows git bash users:
source ./venv/Scripts/activate
# For fish users:
source ./venv/bin/activate.fish

Building and installing

Build and install everything into the virtualenv:

make build

Note

If you're building from source to develop we suggest building/installing using make build DEV=true which installs all Python packages with pip's handy --editable flag. By doing this you wont have to reinstall everything whenever you want to try out a code change.

Running

Now you should be able to start ActivityWatch from the terminal where you've activated the virtualenv. Or, if you were using the PIP_USER trick, from any terminal with a correctly configured PATH. You have two options:

  1. Use the trayicon manager (Recommended for normal use)
    • Run from your terminal with: aw-qt
  2. Start each module separately (Recommended for developing)
    • Run from your terminal with: aw-server, aw-watcher-afk, and aw-watcher-window

Both methods take the --testing flag as a command line parameter to run in testing mode. This runs the server on a different port (5666) and uses a separate database file to avoid mixing your important data with your testing data.

Now everything should be running! Check out the web UI at http://localhost:5600/

If anything doesn't work, let us know!

Note

On Linux, if you want to run from source using a .desktop file launcher, see :issue:`176`.

Updating from source

First pull the latest version of the repo with git pull then get the updated submodules with git submodule update --init --recursive. All that's needed then is a make build.

If it doesn't work, you can first try to run make uninstall and then do a fresh make build. If that fails as well, remove the virtualenv and start over.

Please report all issues you might have so we can make things easier for future users.

Packaging your changes

If you made some changes and want to create a proper build with portable executables (like normal ActivityWatch releases) you need to install pyinstaller (and on Debian-like distros python3-dev).

apt install python3-dev  # Or equivalent for your Linux distribution
pip3 install --user pyinstaller

Then simply run the following to package it:

make package

When the packaging is done you will have ./dist folder where you can find a zipped version and an unzipped activitywatch folder, you can move or copy that folder anywhere you need and set aw-qt to run from startup.