Getting Set Up¶

Git Hooks¶

In order to help prevent some accidental situations, here are some git hooks that may be useful. The scripts below should be places in the .git/hooks directory in the top level of the cloned GitHub repository and be marked executable with e.g. chmod +x pre-commit. For more information on git hooks, see this reference.

pre-commit

This git hook runs the code quality 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 quality
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.

Install npm and node¶

First, install Node.js and npm (node package manager). You can download and install these directly, or use conda to install them from the Bokeh channel on anaconda.org:

conda install -c bokeh nodejs

Alternatively, on Ubuntu you can use apt-get:

apt-get install npm node

Install Gulp and necessary plugins¶

Once you have npm and Node.js installed, you must use them to install the required dependencies before you can build BokehJS. Execute the following commands:

cd bokehjs
npm install

This command will install the necessary packages into the node_modules subdirectory (and list them as devDependencies in package.json).

If bokehjs fails, please check if you are working inside the bokehjs directory.

At this point, you can typically use the setup.py script at the top level of the source checkout to manage the building and installing BokehJS as part of the complete Bokeh library (see Python Setup).

However, if you want to work on the BokehJS sources or use BokehJS as a standalone library, then you need to use Gulp to build the BokehJS library as shown below.

Building BokehJS with Gulp¶

Below are the main Gulp commands for development (to be executed from the bokehjs subdirectory). To run these commands, you can either use bokehjs/node_modules/.bin/gulp, install Gulp globally via npm:

npm install -g gulp

or install gulp via conda (recommended):

conda install -c javascript gulp

To generate the compiled and optimized BokehJS libraries with source maps, and deploy them to the build subdirectory:

gulp build

Additionally, gulp build accepts a --build-dir argument to specify where the built resources should be produced:

gulp build --build-dir=/home/bokeh/mybuilddir

For faster development turnaround, you can skip the very slow minification step of the build by issuing:

gulp dev-build

The non-minified javascript can be used by setting the environment variable BOKEH_MINIFIED=false in the shell.

To direct Gulp to automatically watch the source tree for changes and trigger a recompile if any source file changes:

gulp watch

A Gulp build will automatically generate the sources and their associated source maps. With “source mapping” enabled in your browser, you will be able to:

• debug the original .coffeescript files when using js/bokeh.js
• debug the compiled non-minified javascript when using js/bokeh.min.js
• debug the original .less files when using css/bokeh.css or css/bokeh.min.css

in your developer console.

Dependencies¶

In order to build Bokeh from its source, you’ll have to install the project’s python dependencies. If you’re using Conda or pip + virtualenv to setup a development environment, you’ll be able to install these via conda install or pip install for the packages references at Dependencies.

There are additional testing dependencies required to run the unit tests, which include:

• beautiful-soup
• colorama
• pytest
• pytest-cov
• pytest-selenium >= 1.0
• mock
• websocket-client
• flake8
• boto

Both the build and test dependencies can potentially change between releases and be out of sync with the hosted Bokeh site documentation, so the best way to view the current required packages is the review the meta.yaml file included in the Github repository.

In addition to the build and test dependencies, you must also have the base dependencies for Bokeh installed. A simple way to install these dependencies is to install Bokeh via conda install or pip install before running setup.py. Alternatively, you can download them individually. The dependencies include:

• jinja2
• numpy
• dateutil
• pyyaml
• requests
• tornado

To quickly and easily confirm that your environment contains all of the necessary dependencies to build both the docs and the development version of Bokeh, run the devdeps.py file inside the bokeh/scripts directory.

If any needed packages are missing, you will be given output like this

------------------------------------------------------------------
You are missing the following Dev dependencies:
 *  beautiful-soup

------------------------------------------------------------------
You are missing the following Docs dependencies:
 *  sphinx
 *  pygments

Otherwise, you should see this message

------------------------------------------------------------------
All Dev dependencies installed!  You are good to go!

------------------------------------------------------------------
All Docs dependencies installed!  You are good to go!

Additionally, devdeps.py will check that the bokehjs/node_modules directory exists, which is where npm packages are installed.

If this directory is not found, it will provide instructions on how and where to install npm packages.

Windows Notes¶

If you build Bokeh on a Windows machine in a Conda environment with either setup.py install or setup.py develop, running bokeh serve will not work correctly. The .exe will not be available within the Conda environment, which means you will use the version available in the base install, if it is available. Instead, you can make sure you use the Python version within the environment by making use of Python’s -m flag, as in the following example:

python -m bokeh serve path\to\<yourapp>.py