Sugar: Intro to Sugar 5
completed by: shaunak
mentors: Amaury Medeiros, Arc Riley, David Czech, Jon Neal, AJ Williams
Sugar is the operating system for the One Laptop Per Child "XO" laptops being used by over 2.4 million students and teachers around the world.
As PySoy targets lower-powered machines, is designed for use by all ages, and uses the same technologies (eg, Python, Glib, XMPP) its an ideal 3d game engine to run on Sugar. You can help make that happen, and a good first step is booting Sugar and installing PySoy on it.
If you've completed PySoy: Intro to Linux Development these steps will look very familiar - that's because Sugar is Linux-based. However, because this task works on a bootable USB drive, it is especially well suited for new students who only have access to OSX or Windows computers.
You will need Sugar on a Stick to get started. Download it and follow the installation instructions to make a bootable USB stick. As you go through the directions and install options, ensure your bootable USB will have persistent storage so your work is stored after you reboot.
Its highly recommended to make a physical Sugar on a Stick and boot it for full access to graphics hardware. On OSX, you hold down the Option key as the computer turns on to enter the boot drive selector. On Windows machines there is often a message to press a function key as the computer is booting.
One of the first things you should do after booting Sugar on a Stick is connect to IRC (Internet Relay Chat) to get help should you run into any trouble. Load up Sugar's IRC Activity and join #CopyleftGames on irc.freenode.net. Getting comfortable with IRC now will make this task easier and help you as you continue with Google Code-in tasks.
[IMAGE http://gci.copyleftgames.org/img/icons/irc.png]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.
To begin compiling PySoy, you will first need to install Mercurial.
Mercurial is a version control system (VCS) which allows 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.
[IMAGE http://gci.copyleftgames.org/img/icons/fedora.png]Sugar is based on Fedora and includes Fedora's package manager called "yum".
Package managers provide an easy way to search, install, and update thousands of software packages - including many Linux programs not available as a Sugar activity.
Open a Terminal activity and type sudo yum 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 the Terminal activity 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 called "Fedora Quickstart" with a very long sudo yum command you can copy and paste.
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.
[IMAGE http://gci.copyleftgames.org/img/icons/waf.png]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.
Press ALT 1 to take a screenshot of these bouncing cubes and upload the screenshot from your journal to this task. Also upload a text file containing any difficulty you had or suggestions for improving this task.
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. Code updates which may affect your work are also announced here as they happen.