Complete Roguelike Tutorial, using python3+libtcod, setup Mac
This is part of a series of tutorials; the main page can be found here. |
Setup Mac
Installing an Editor
Editors are often a personal choice. Their primary function is to allow the creation and editing of code. Additional functionality may be included such as code intelligence, code completion, static analysis, testing, debugging, etc. usually through plugins. Some editors are also IDEs or integrated development environments. They can help manage the lifetime of a project. For this tutorial, you only need an editor and none of the extra functionality, but an IDE may be very helpful when learning programming (or Python) for the first time.
The following editors are all excellent for python development. You only need one.
Note that these are listed in order of decreasing preference for development with python as a beginner. (i.e. pick one of the top ones for the best out of the box python experience)
Setting up Bash
Open finder (cmd + space) and go to your home folder and then press CMD + SHIFT + . (command + shift + period). Look for a ".bashrc" file within finder. Open it up in your editor or create a new file. Make sure the following lines show up at the bottom of the file:
# Setup prompt colors
reset_color="\[\e[m\]"
declare -A fg
magenta="\[\e[35m\]"
yellow="\[\e[33m\]"
green="\[\e[32m\]"
function virtualenv_prompt() {
if [ -n "$VIRTUAL_ENV" ]; then
pyver=$(python -V 2>&1 | cut -f2 -d' ')
echo "(${magenta}venv${reset_color}:${yellow}${VIRTUAL_ENV##*/}$reset_color|${green}${pyver}${reset_color}) "
fi
}
export PS1="$(virtualenv_prompt)${PS1}"
export LIBTCOD_DLL_PATH="/usr/local/lib;/usr/lib;$HOME/.local/lib;$HOME/lib"
Opening a Terminal
While Mac comes with a Terminal built-in, Iterm2 is the recommend install for a terminal. Once installed, simply press `Cmd + Space Bar` and type in iterm or terminal (for the default mac terminal). Whether you've installed iterm or are using the default terminal, we will use the word "terminal" below to refer to your preferred program (iterm or terminal).
Setting up Homebrew
Homebrew is a package manager for Mac. Within a terminal, type the following to install homebrew:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Setting up Mercurial
Now that we have homebrew, we can install several dependencies. Mercurial allows us to download the `libtcod` library from `bitbucket.org` where the source code resides. Mercurial is an alternative to Git for software configuration management. Within a terminal, run:
brew install mercurial
Setting up Python
Because we would like to build libtcod with scons, we'll need to make sure that we have both Python 2 and Python 3 installed. To install the latest of both python versions, simply run within a terminal:
brew install python@2 python3
To validate that we've installed python2 correctly, within a terminal, run:
python2 --version
The version should be at least "Python 2.7.15".
To validate that we've installed python3 correctly, within a terminal, run:
python3 --version
The version should be at least "Python 3.6.5".
Setting up Python dependencies
Pip
Python 3 comes bundled with a python package manager called `pip`, but python 2 does not. To make sure we have `pip` installed run in a terminal:
python2 -m ensurepip
Python Virtual Environments
Additionally, we'll want the scons build system ready to go for libtcod. The correct way to isolate python packages is using a virtual environment, which sandboxes python versions and their packages. While Python 3 has this built in, python has a 3rd party tool called `vex` to manage the sandboxes and can be installed as follows:
python2 -m pip install vex
Installing libtcod
At this point, we should be ready to download and install libtcod. There are several basic steps required to make this work.
- install libtcod dependencies
- download the source code from bitbucket using mercurial
- build the source code with scons from within our virtual environment
- move the resulting library file (libtcod.dylib) into a proper folder
Install libtcod dependencies
Libtcod relies upon SDL2 to run. To install sdl, run within the terminal:
brew install sdl2
Download libtcod
The build process is fairly straight forward, but first we need to download the source code from bitbucket.
cd $HOME
mkdir -p $HOME/repos/other/
cd $HOME/repos/other
hg clone https://bitbucket.org/libtcod/libtcod
Build libtcod
Creating a libtcod build environment
Now that we have `vex`, we can create a virtual environment to install scons. Running the following command will both create the virtual environment, libtcod-build, as well as enter the virtual environment.
vex --python python2 -m libtcod-build
You should now see a prompt that looks something like this:
(venv:libtcod-build|2.7.13) bash-3.2$
Installing scons within Virtual Environment
To install scons, we simply use `pip` from within the virtual environment:
(venv:libtcod-build|2.7.13) bash-3.2$ pip install scons
Build using Scons
We'll want to build from the scons folder.
(venv:libtcod-build|2.7.13) bash-3.2$ cd libtcod/build/scons/
(venv:libtcod-build|2.7.13) bash-3.2$ scons build
(venv:libtcod-build|2.7.13) bash-3.2$ cd ../../
This should produce a mac binary library file called "libtcod.dylib" under a new folder, libtcod-1.6.4-x86.x86_64-DEBUG. You can check to see if the file is created:
(venv:libtcod-build|2.7.13) bash-3.2$ find . -name "libtcod.dylib"
Installing libtcod
The best place to put the new library file, `libtcod.dylib`, is in a system folder: `/usr/local/lib`. The rules for path resolution for finding `libtcod.dylib` within the python library are as follows:
1. Look for `libtcod.dylib` in the python `site-packages` folder where the python library was installed (this will be in a virtual environment path) 2. Look for `libtcod.dylib` from where the current script is being executed (so, for example, where you run your rogue-like project) 3. Look for any paths defined within the environment variable, `LIBTCOD_DLL_PATH` (we defined this in our .bashrc file)
To install in the recommended system path:
(venv:libtcod-build|2.7.13) bash-3.2$ mkdir -p /usr/local/lib
(venv:libtcod-build|2.7.13) bash-3.2$ cp `find . -name "libtcod.dylib"` /usr/local/lib
Validating libtcod Installation
Run the following command:
(venv:libtcod-build|2.7.13) bash-3.2$ python -c "import libtcod"
Setting up your Project
Creating a virtual environment
To exit out of the python 2, libtcod-build virtual environment from above, just type in "exit" or press: control + d
We'll want to make sure we have a python 3 environment going forward, and we need to make sure that we've installed libtcod within that virtual environment.
To create a new virtual environment with python 3 for our project, just use the following:
vex --python python3 -m rl
You should now be in your virtual environment
(venv:rl|3.6.2) bash-3.2$
To make sure, test your python version. You should see something like version "3.6.2".
(venv:rl|3.6.2) bash-3.2$ python --version
Installing libtcod into our project
Navigate to where libtcod was downloaded and then run the installation or libtcod:
(venv:rl|3.6.2) bash-3.2$ cd $HOME/repos/other/libtcod/python
(venv:rl|3.6.2) bash-3.2$ pip install .
(venv:rl|3.6.2) bash-3.2$ cd -
Validate that we have libtcod installed.
(venv:rl|3.6.2) bash-3.2$ python -c "import libtcodpy"
Folder structure
Our first roguelike will be run entirely from a single file, firstrl.py. However, to support some future needs regarding packaging and to make development easier, we need to add our dependencies into the project folder.
When we're all done, the basic folder structure should look like this:
- \project\
- \firstrl.py
mkdir -p $HOME/repos/mine/roguelike
touch $HOME/repos/mine/roguelike/firstrl.py
Finishing touches
Congratulations!
You're ready to start editing firstrl.py!
Now you're ready to start writing code.