PySoy: Intro to Linux Development 44
completed by: Skyhawk
mentors: Amaury Medeiros, Arc Riley, David Czech, Jon Neal, AJ Williams
While PySoy is intended to be cross-platform, it is primarily developed on Linux which provides most (or all) of its dependencies packaged as system-wide shared libraries, an easy to use build system, and great community support.
If you already have Linux installed (or wish to do so, see getfedora.org), pick this as an introduction to developing PySoy.
This guide assumes no prior experience with Linux, shells, version control, build systems, or IRC. If you're an experienced Linux user, please just do this without claiming this task since you may only complete two beginner tasks and we have many to choose from.
Before getting started, you will want to connect to IRC (Internet Relay Chat) to get help should you run into any trouble. You can use webchat.freenode.net in your browser for now, but you may want to consider using a desktop IRC client such as Empathy or XChat. Getting comfortable with IRC now will make this task easier and help you as you continue with Google Code-in tasks.
Internet Relay Chat is one of the oldest Internet protocols, predating HTTP and the web. While not commonly used by casual Internet users, and there are more modern protocols supporting features like images and voice/video chat, many FOSS projects still use IRC for developer chat - and most have a channel on the Freenode network.
To chat in IRC just type and hit [enter]. Commands begin with the "/" character, such as /connect irc.freenode.net to connect to Freenode if you've not already done so.
Every user on Freenode has a unique nickname. Some nicknames are registered by other users so NickServ will tell you it is not available. You can change your nickname at any time with the /nick command, eg, /nick GCIUser
IRC is made of channels (think, "chat rooms") which start with a pound sign, such as "#CopyleftGames". On Freenode, you can expect to find a channel for almost any FOSS project, eg, #Fedora, #Python, #Ubuntu. To join a channel, use the /join command, eg, /join #CopyleftGames
Please keep in mind that during Google Code-in mentors are often swamped with helping students and reviewing tasks. They are not likely staring at an IRC window right when you join and may not see what you write for several minutes. However, especially for beginner tasks, other Google Code-in students are usually happy to help.
Let's get started - grab a notebook or open a text document to take notes as you go, especially on areas you had difficulty with.
The first thing you need to do is learn how to install already packaged software in order to install Mercurial.
Mercurial is a version control system (VCS) similar to Git (what github uses) and others. These programs allow many people to edit source code, record each developer's contributions, and merge their changes together. Installing Mercurial gives you the "hg" command (the chemical symbol for Mercury) which you'll need next.
There are many distributions of Linux to choose from, Arch, Debian, Fedora, Gentoo, Mint, and Ubuntu to name a few. Each of these provides a package manager.
Package managers provide an easy way to search, install, and update thousands of software packages from either an AppStore-like tool or in the Terminal application, eg;
- On Fedora:
sudo yum install mercurial - On Gentoo:
sudo emerge mercurial - On Mint and Ubuntu:
sudo apt-get install mercurial
Note the sudo command - this stands for "Switch User and Do".
Whatever command follows sudo will be executed as the system administrator (also known as the root user). Use this command with caution if you're new to Linux, but you will need it to install software.
Type hg clone http://hg.pysoy.org/libsoy into a Terminal to download the libsoy source code using Mercurial (the "hg" command). To get familiar with working with the Terminal, type these one by one:
lsto list the files in your current directorycd libsoyto change directories to libsoypwdto print working directory, ie "where am i"lsagain to see the contents of the libsoy directoryless INSTALLto read the INSTALL directions
If you scroll down while viewing INSTALL you'll find a section specific to your Linux distribution (eg, "Fedora Quickstart") with directions you can usually just copy and paste to a terminal. Does this command look familiar? These commands are to install all the software you need to build libsoy using your package manager, just like installing Mercurial before.
Type ./waf configure which will verify and find all the things needed to compile and run libsoy (many of which you installed in the previous step). If it says it can't find something, you likely didn't copy/paste the whole command (usually multiple lines) in the previous step. Ask for help if this still doesn't work.
If you type "ls" you'll see a file called "waf" in the libsoy directory. This is a Python-based program that greatly simplifies the steps needed to compile, link, and install software. There are three main steps, each as a separate waf command:
- waf configure searches for the programs and libraries we need
- waf build runs the compiler commands to build from source code
- waf install copies the software to system directories
You can learn more about waf on their website: https://code.google.com/p/waf/
Now ./waf build command to compile libsoy. This may take a few minutes the first time you run it, and you may see several warnings which you can ignore for now (there are Google Code-in tasks to clean these up).
If everything went well, type sudo ./waf install to install libsoy. Generally this goes into /usr/local with other software you compile and install by hand (vs with package manager).
Lets see what you've learned!
Type cd ~ to return home ("~" means home directory).
Use Mercurial to clone http://hg.pysoy.org/pysoy
Change directory to the new pysoy directory and use the same waf commands to configure, build, and install as you did with libsoy.
Test your installation by changing to examples directory and type ./CollideBlocks.py
If all went well, a window will pop up with checkered blocks with round edges spinning and smashing into each other. This is one of the programs we commonly use to ensure the rendering and physics engine is working properly.
Hit the Print Screen key (or another method to take a screenshot) as proof of task completion.
While working on this task you should join and remain in #CopyleftGames on Freenode to get help, feedback, and guidance from mentors and other developers.
When you've done, post the screenshot and your notes to this task.