Getting Set Up¶

Git¶

The Bokeh source code is stored in a Git source control repository. The first step to working on Bokeh is to install Git on to your system. There are different ways to do this depending on whether, you are using Windows, OSX, or Linux.

To install Git on any platform, refer to the Installing Git section of the Pro Git Book.

Conda¶

Developing Bokeh requires installing some software packages that are not Python packages (e.g. Selenium, NodeJS, etc.). To make this more manageable, core developers rely heavily on the conda package manager for the free Anaconda Python distribution. However, conda can also install non-Python package dependencies, which helps streamline Bokeh development greatly. It is strongly recommended that anyone developing Bokeh also use conda, and the remainder of the instructions will assume that conda is available.

To install Conda on any platform, see the Download conda section of the conda documentation.

Conda environment¶

Setting up an isolated conda environment to guarantee package compatibility is considered best practice. To set up a clean environment, issue the following command:

conda create --name bokeh-dev

Then, to activate the environment:

conda activate bokeh-dev

Conda Packages¶

On all platforms, execute the following two commands at your command prompt to add the “bokeh” and “conda-forge” channels to your list of package sources:

conda config --append channels bokeh
conda config --append channels conda-forge

It’s also necessary to install jinja2 and pyyaml first, to bootstrap the rest of these instructions. To do that, execute:

conda install jinja2 pyyaml

From the top level of the source checkout directory, execute the following command at your command prompt to install all the required packages:

• OSX / Linux (bash / sh)

  conda install `python scripts/deps.py build run test`
  

  Note the required backticks in the command.

• OSX / Linux (fish)

  conda install (python scripts/deps.py build run test | string replace -ar '\s\s+' ' ' | string split ' ' | string escape)
  

• Windows (Powershell)

  conda install $(python scripts/deps.py build run test).split() | where {$_}
  

• Winows (DOS Command Prompt)

  for /F "delims=" %i in ('python scripts\deps.py build run test') do (conda install %i)
  

Node Packages¶

Building BokehJS also requires installing JavaScript dependencies using the Node Package Manager. If you have followed the instructions above, conda has already installed the necessary npm and node.js packages to your system.

Bokeh is typically updated to require the latest major revision of npm in order to build. To install the lastest version globally, start from the top level of the source checkout directory, and execute the following commands

cd bokehjs
npm install -g npm

If you do not wish to install globally (i.e. with -g) then all subsequent npm commands will need to be adjusted to use the local version installed under bokehjs/node_modules.

Next, still in the bokehjs subdirectory, execute the following command to install all of BokehJS JavaScript dependencies:

npm install --no-save

This command will install the necessary packages into the node_modules subdirectory.

PhantomJS¶

PhantomJS is currently required to exercise some capabilities under test. It is available via Conda for some platforms. For other platforms, it may be installed via npm with: npm install -g phantomjs.

Typically, these instructions only need to be followed once, when you are first getting set up. Occasionally, however, dependencies may be added or changed, in which case these instructions will need to be followed again.

Git Hooks¶

In order to help prevent some accidental errors, here are some git hooks that may be useful. The scripts below should be placed in the .git/hooks subdirectory in the top level of the source checkout directory and be marked executable with e.g. chmod +x pre-commit. For more information on git hooks, see this turorial.

pre-commit

This git hook runs all the codebase tests before allowing a commit to proceed. Note that all the standard testing dependencies must be installed in order for this hook to function.

#!/bin/bash

py.test -m codebase
exit $?

pre-push

This git hook prevents accidental pushes to master on GitHub.

#!/bin/bash

protected_branch='master'
current_branch=$(git symbolic-ref HEAD | sed -e 's,.*/\(.*\),\1,')

if [ $protected_branch = $current_branch ]
then
    read -p "You're about to push master, is that what you intended? [y|n] " -n 1 -r < /dev/tty
    echo
    if echo $REPLY | grep -E '^[Yy]$' > /dev/null
    then
        exit 0 # push will execute
    fi
    exit 1 # push will not execute
else
    exit 0 # push will execute
fi

Git Aliases¶

There are also some useful aliases that can be added to the .gitconfig file located in your home directory.

The following alias adds a git resolve command that will automatically open up your editor to resolve any merge conflicts.

[alias]
    resolve = !sh -c 'vim -p $(git status -s | grep "^UU" | cut -c4-)'

You can replace vim with whatever your favorite editor command is.