Dev Environment Setup
This page will describe the suggested way to configure a dev environment suitable for contributing to this project. There are other ways to solve this problem, but this is a good resource for new devs that need to get up-and-running quickly.
Updates to the codebase or dev best practices that change the basic process required to get an up-and-running dev environment should document themselves on this page. Software that is strictly required for running our code, not merely nice to have for a dev environment, should be documented in the Dependencies wiki and referenced here.
We currently only support Linux, although Mac support will likely happen eventually. See the Linux section of the Dependencies wiki for details.
We're using a current version of Python this year, compared to the legacy 2.7 we used last year. Unfortunately, most distros still ship 2.7.X by default.
[~bot]$ python --version
Python 2.7.5
See the Python 3.4.0 section of the Dependencies wiki for details of the install process.
We suggest using a virtual environment to isolate the packages, libraries and such you need for this project from the ones that are installed on your system generally. If you don't know much about virtual environments, take a moment to read this excellent introduction.
You can install virtualenv from your distro's repos.
[~bot]$ sudo apt-get install python-virtualenv
You'll use PIP to download and install Python packages. It comes bundled with virtualenv, so if you're following this guide in-order you already have a copy. Note that PIP will not be installed system-wide after simply a virtualenv install. PIP will only appear be installed when you're in a virtualenv.
PIP doesn't appear to be installed outside of a virtualenv:
[~bot]$ where pip
pip not found
However, as soon as I activate the virtualenv, PIP is in my path and ready for use:
[~bot]$ source ../venv/bin/activate
(venv)[~bot]$ where pip
/home/daniel/robot/current/venv/bin/pip
Go ahead and install PIP system-wide as well. You can grab it from your distro's repo:
[~bot]$ sudo apt-get install python-pip
[~bot]$ where pip # PIP is now installed system-wide
/usr/bin/pip
/bin/pip
There's an excellent project called virtualenvwrapper that basically uses a bunch of scripts to make your interactions with virtualenv much more efficient. For more info, see this outstanding resource.
Use your system-wide install of PIP to install virtualenvwrapper. To be very explicit: don't do this inside a virtualenv, do it when you have a normal prompt (use deactivate to exit a venv if necessary).
[~bot]$ sudo pip install virtualenvwrapper # Note that I'm *not* in a virtualenv
You need to do some minor configuration before virtualenvwrapper will function properly.
First, figure out where virtualenvwrapper installed the script that activates it:
[~]$ which virtualenvwrapper.sh
/usr/bin/virtualenvwrapper.sh
Note that path that's printed as a result of that command. You'll need it here in moment.
You need to add some commands to the file that runs when you start a new shell, so they automatically configure virtualenvwrapper in every new shell. There's a very good chance your shell is Bash, and if that's not the case you already know how to do this. Confirm your shell with this command:
daniel@xen-sd:~$ echo $SHELL # The different prompt is because this is my server (dev system runs ZSH)
/bin/bash
Assuming you see a path to the bash binary printed when you run the command above, you'll want to edit your ~/.bashrc to add the following lines. Adding them to the end of the file is fine. Replace <path to virtualenvwrapper.sh> with the path that was printed in the step above.
export WORKON_HOME="$HOME/.virtualenvs" # You can customize this if you'd like to store your venvs elsewhere
source <path to virtualenvwrapper.sh>
You can now save and close your ~/.bashrc file. Source it to make the changes take effect:
daniel@xen-sd:~$ source ~/.bashrc
You now need to create a virtual environment for all of the packages, libraries and such associated with bot development. The following command syntax will assume you installed and configured virtualenvwrapper, but it's totally possible to do this just using virtualenv without virtualenvwrapper.
First, find the path to Python 3.4:
[~]$ which python3.4
/usr/local/bin/python3.4
For most versions of Python, you'd normally pass that path to mkvirtualenv (mkvirtualenv -p /usr/local/bin/python3.4 vbot), to tell it to create a new virtualenv using Python 3.4. However, I'm currently seeing an error while attempting to build a venv via that method. Creating a venv with pyvenv-3.4 (which was installed with Python 3.4) in the place expected by virtualenvwrapper seems to bypass this issue:
[~]$ echo $WORKON_HOME # virtualenvwrapper expects venvs to be stored in this directory
/home/daniel/.virtualenvs
[~]$ where pyvenv-3.4 # This was installed with Python 3.4
/usr/local/bin/pyvenv-3.4
[~]$ pyvenv-3.4 $WORKON_HOME/vbot # Use pyvenv-3.4 to get a venv with Python 3.4
[~]$ lsvirtualenv # virtualenvwrapper knows about the new venv
vbot
====
[~]$ workon vbot
(vbot) [~]$ python --version # The new venv is using Python 3.4, yay!
Python 3.4.0
If you see an import error here related to zlib, go back to the Python 3.4.0 section of the Dependencies wiki for details about how to fix it.
Note that I'm now in the newly created vbot virtual environment, as indicated by my shell $PS1 and my path:
(vbot)[~]$ which python
~/.virtualenvs/vbot/bin/python
Whenever you're doing bot development, you'll want to have this virtual environment active. You can activate and deactivate like this:
(vbot)[~]$ deactivate
[~]$ which python # Not needed, just showing that I'm not in the venv
/usr/bin/python
[~]$ workon vbot
(vbot)[~]$ which python # Not needed, just showing that I'm in the venv
~/.virtualenvs/vbot/bin/python
We use git to version control our code. It's awesome, and you really should take some time to learn about it. If you're unfamiliar with git, I strongly suggest following this excellent 15 minute interactive introduction. Additionally, here is a written, slightly more detailed resource. Finally, this is a good video and activity based method to learn git (paywalled after first section).
You can install git from your system's repo:
[~]$ sudo apt-get install git
You'll want to do some basic configuration. There are two easy ways to knock this out. Both end up creating the configuration file ~/.gitconfig. The CLI method creates this file in a series of steps. Manually copying and editing my example accomplishes the same task.
To populate the required parts of your ~/.gitconfig, issue the following commands (replacing the name and email with your own):
[~]$ git config --global user.name "Your Name"
[~]$ git config --global user.email "[email protected]"
The remaining configuration is optional but recommended:
[~]$ git config --global core.editor vim
[~]$ git config --global core.autocrlf input
[~]$ git config --global color.ui true
[~]$ git config --global alias.logg "log --graph --oneline"
[~]$ git config --global help.autocorrect 1
Those commands will create your git configuration file ~/.gitconfig (example below).
You can directly copy and edit this file, as an alternative to the commands above.
[user]
name = "Your Email"
email = "[email protected]"
[core]
editor = vim
autocrlf = input
[color]
ui = true
[alias]
logg = log --graph --oneline
[help]
autocorrect = 1
This is a good git customization resources.
In order to avoid having to type your GitHub authentication information painfully frequently, you'll want to generate a public key pair for authentication with GitHub.
[~/robot/current]$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/daniel/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/daniel/.ssh/id_rsa.
Your public key has been saved in /home/daniel/.ssh/id_rsa.pub.
<snip>
You now have a public key pair, composed of a public and private RSA key, in ~/.ssh.
[~/.ssh]$ ls
config id_rsa id_rsa.pub known_hosts
On GitHub, navigate to your profile, then select "Edit Your Profile" from the upper right corner, and finally choose "SSH Keys" from the field on the left.
Choose the "Add SSH Key" option and give your key a name. Finally, copy the complete contents of ~/.ssh/id_rsa.pub into the "Key" field.
Click the green "Add Key" button to submit the key.
You'll now be able to authenticate to GitHub from this machine, using your new keypair.
This repo contains the main codebase for our 2015 robot. First, create or naviate to the directory where you want to store our code. I typically use a ~/robot/current/ directory that tracks the current year's work:
[~/robot]$ ls
2012 2013 2014 current
[~/robot]$ cd current
[~/robot/current]$
Clone this repo (IEEERobotics/bot):
[~/robot/current]$ git clone [email protected]:IEEERobotics/bot.git
Cloning into 'bot'...
<snip>
[~/robot/current]$ cd bot # Enter the newly cloned repo
[~bot]$ git remote -v # Show that I'm in a copy of our repo
origin [email protected]:IEEERobotics/bot.git (fetch)
origin [email protected]:IEEERobotics/bot.git (push)
We've broke quite a bit of functionally out into other open source projects that are more amenable for consumption by other community members.
Before installing these packages, activate your virtual environment! Doing so will allow you install them to your bot development environment only, not to your full system:
[~bot]$ workon vbot # Assuming this is the name used when creating your venv above
(vbot) [~bot]$ python --version # Just confirming that I'm using Python 3.4 in my venv
Python 3.4.0
You can check which packages you have installed to your venv using pip freeze.:
(vbot) [~bot]$ pip freeze # I have no packages installed to my venv
(vbot) [~bot]$
You can easily install all of our projects, as well as most of our other dependencies, simply by pointing pip install at the included requirements.txt file:
(vbot) [~bot]$ pip install -r requirements.txt
<snip>
Successfully installed PyYAML i2c-device pyDMCC
Cleaning up...
(vbot) [~bot]$ pip freeze # Show newly installed packages
PyYAML==3.11
-e git://github.com/jschornick/i2c_device.git@4532e94cd02cdf428a3c7a245ac0abc9886c1278#egg=i2c_device-origin/master
-e git://github.com/IEEERobotics/DMCC_Library.git@f698e78c24aa99f1ec70b3c8d52017e93791a275#egg=pyDMCC-origin/master
TODO: Link to API repo install process description?
Head over to the dependencies wiki's ZMQ section for details on how to install ZMQ. Since it requires libzmq, which will be supplied by a package manager like APT or yum instead of pip, it's less likely to cause issues if you install pyzmq with that same package manager instead of pip.