-
Notifications
You must be signed in to change notification settings - Fork 33
Getting started
It is helpful if you have a very basic understanding of your terminal emulator (command prompt in Windows). If you don't have that yet, you may want to look for a quick tutorial on the internet before proceeding. Most essential is that you know how to start the terminal and how to use the command cd.
In addition to some basic terminal skills, you need to have Python 2.7 installed. Check Dependencies.md for other (optional) dependencies.
There are two ways of obtaining the project. The first is recommended, but it requires you to install Git. The second option only requires a zip archive extracting program, but it doesn't allow you to contribute to the repository.
If you haven't done so before, install Git. (Windows users: you may want to consider MSysGit instead. Mac users: you already have Git if you installed Xcode. Linux users: you can almost certainly obtain Git through your package manager.) You also need to create a GitHub account.
Once you have Git and a Github account you can just fork and clone the repository (explained in detail right below). It is recommended that you clone the repository somewhere in your home folder so you don't need to mess with permissions. For now we'll assume you're going to install the project in RedSpider, a direct subfolder of your home directory (which is where you start when you open a new terminal window).
- Go to https://github.com/the-xkcd-community/the-red-spider-project and click on the "Fork" button in the topright corner of the page.
- Open a terminal window.
- Run the following commands:
git clone https://github.com/<yourname>/the-red-spider-project.git RedSpider cd RedSpider git remote add upstream git://github.com/the-xkcd-community/the-red-spider-project.git
(You can also clone your own fork using SSH. See this tutorial and this one for an explanation.)
Now you're all set! Take a few tutorials at GitImmersion if you want to understand Git better. See the GitHub tutorial if you want to know more about forking.
Direct download. Extract it somewhere in your home directory. If you don't have a zip extractor yet, 7zip is a good choice for Windows.
cd into the folder where you cloned or extracted the Red Spider Project (this is called the project root directory or RED_SPIDER_ROOT) and run ./setup.py (the ./ is optional on Windows). The installation program will explain itself. Literally!
NOTE: If you run setup.py for the first time in a directory, the effect will not be immediately visible. To "update" your terminal, run
for /f "tokens=3* skip=2" %i in ('reg query "HKCU\Environment" /v RED_SPIDER_ROOT') do (set RED_SPIDER_ROOT=%i)
on Windows or
source ~/.profile
on Mac or Linux.
When using the Red Spider Project software you always start by running rsshell. It's like your portal to the Red Spider world. Once you're in that world you can run the other commands that were installed. For example you could try this:
xkcd-fetch -r
It spits out the metadata of a random xkcd comic to you, possibly after downloading it first. You might be more interested in the image; it's saved in $RED_SPIDER_ROOT/work/xkcd-fetch (Windows: %RED_SPIDER_ROOT%\work\xkcd-fetch). Try this fancy command to have the image of a random comic thrown at you:
summon $RED_SPIDER_ROOT/work/xkcd-fetch/`xkcd-fetch -r | json-parse image_name`
(the Windows version has % and \ just like in the previous comment).
You can see what commands are available at any time by running rshelp. This command can also explain a topic, including itself, if you run rshelp <topic>.
To go back to the normal world (i.e. stop rsshell), run exit.
If you can't get things to work, ask for help on the xkcd forums thread or on our IRC channel: #redspider at irc.foonetic.net. Those are also the places for giving general feedback. If you come across a bug while using the software or if you have a feature request, please use the issue tracker.