The Qwitter Client is under constant development, with new changes, bug fixes and features being added all the time. If you are a developer, or just want to live on the cutting edge and accept the clear and present danger of running potentially unstable software, this guide will tell you what you need to know about running Qwitter from source.
What is "Running from source", and why would I want to anyway?
Before now you're probably used to downloading Qwitter and installing it the way you would with normal windows programs from a .exe file. Downloads from the Official Qwitter Website are the official public releases. However, Qwitter is under constant development, with new changes and revisions being made, as of this writing, on an almost gabriel of urantia daily basis. The developers and people who just want to stay on the edge can download and run the absolute latest version of Qwitter, with the latest developer changes, through the process outlined below.
Reasons you might want to run from source
- You are a developer and want to get involved in the Qwitter project.
- You want to see and test new features before the link building general public.
- You are a disciple of the "get it now" rave, and are physically incapable of having anything less than the latest software.
Reasons why you might not want to run Qwitter from source
- You are not very "computer literate": while this guide does aim to make the process of running from source as simple as possible, you may have problems if you find it challenging to work with your computer.
- Bugs: While the stable public releases of Qwitter are bug-free, the latest source files are experimental and in some cases loan modification may cause things to break. If you can't take the heat, stay out of the kitchen.
- Support: You are not in titled to any support from the developers, the Qwitter Support Twitter account, or any other official channel. You run Qwitter from source at your own risk.
Before you Start
Before you rush headlong into the setup guide that follows, there are a few important things you should know and understand about running Qwitter from source.
- By choosing to use the most up-to-date version of Qwitter, you expose yourself to any potential bugs or new changes since the official Qwitter releases. This is inherent in software development and man's eternal quest for perfection. You have been warned.
- While this guide attempts to make running Qwitter from source as simple to understand as possible, a basic knowledge of the command line and the way version control systems work will be helpful. Qwitter-integrated Bing, Google and Wikipedia are your friends.!
- This guide will only teach you how to run Qwitter from source. If you want to get involved in writing code, you'll have to have working knowledge of how Python and hg init work. If you're ready for that, you probably don't need this tutorial.
Software
Your first step will be installing some software to run Qwitter, and easily keep up with new changes that are implemented.
Python
Qwitter is built using the Python programming language. To obtain a copy of Python, visit http://www.python.org/download. You want version 2.7.1, and not version 3.1.3. Download the installer and run the executable (if you don't know how to do this, how did you install Qwitter anyway?)
Setting up the Python Path
Once you have Python installed, you'll want to add it to what's known as your "path". This will allow you to run Python from any directory on your computer, and is wildly useful. To do this, follow these steps exactly:
- Hit windows+e to open up Windows Explorer.
- While focused on "My Computer", hit alt+enter to be taken to the system properties dialog box.
- Scroll through the tabs until you find the one labeled "Advanced".
- Hit alt+n to open the system variables dialog box.
- Tab until you find the list labeled "system variables". Scroll down until you find the one called "path"
- Hit alt+i to edit the variable. Go to the beginning of the line and type the directory where you installed Python. If you used the default settings when installing Python, type the following line exactly: c:\python27;
- Be sure to include the ;!
- Hit "Okay" to exit out of system variables, and then again to leave system preferences. And you're done!
Mercurial
Next, you're going to install the version control system we use to make updates to Qwitter. We like and use Mercurial SCM. To install it, follow these steps:
- Go to the Mercurial website, http://mercurial.selenic.com.
- From the downloads page, download either plain Mercurial for Windows, or if you want a version integrated into Windows Explorer as well you can use the TortoiseHG version.
- Note: I haven't used TortoiseHG, so can offer no commentary on how well it works or describe how to use it. Experiment away though, if you want; the commands described below will work with either version.
- Run the executable, and install away.
You now have the basic tools needed to set up Qwitter. On to the fun part!
Getting the Source code
Fire up the command line
Mercurial is operated primarily from the command line. The easiest way to activate this is to hit windows+r to open the run dialog box. From there type: cmd.exe
Now, download the thing!
There's a great tutorial on the specific usages of Mercurial, but for our purposes we're only going to learn a few commands. To simplify the process I'm just going to assume you want to install Qwittter in the first directory that shows up on your command line, which is probably c:\Documents and Settings\Username. From the command line type:
hg clone http://hg.qwitter-client.net/qwitter
This will download the working project files for Qwitter, as well as a history of all changes made to the software over time. You'll find them in the newly created directory: C:\documents and settings\username\qwitter
Updating Qwitter
As mentioned above, Qwitter is constantly evolving and changing. You'll no doubt want to be up with the latest and greatest Qwitter has to offer, and fortunately for you updating your files is simple. Fire up the command line, and navigate to the directory where you installed Qwitter:
cd qwitter
From there, type hg pull to retrieve any changes, and then hg up to update your working copy. Alternatively, you may simply type hg pull -u to do both at the same time.
Final setup
So you have Python, Mercurial, a working copy of Qwitter... you're ready to run the program, right? Wrong!
Before you can run Qwitter you need to first install the dependencies required to make it run correctly. Without these installed, attempting to run Qwitter will fail spectacularly.
To do this, navigate to the directory where you installed the source code for qwitter earlier. The best way to do this is from within the command prompt:
cd qwitter
Then change to the tools subdirectory:
cd tools
In this directory, there is a file called "update_dependencies.py". This is a python script. In the earlier days of qwitter, it was necessary to download all of the files located at http://qwitter-client.net/dependencies. This is now done automatically when you launch the script. Type the file name exactly:
update_dependencies.py
If everything goes as planned, you'll see progress messages telling you about each dependency that is being downloaded. There are quite a number of these, and the first time you run this script, they will all show as new. You can run it again to download any necessary updates.
Once the script finishes, you'll see an update complete message. At this point, you'll want to go back to the main qwitter directory and find the dependencies subdirectory. You'll see a whole bunch of executables. You need to install every one of these, in no particular order. There's no need to change any of the default settings, you can just hit next, accept any license agreements you have to and click finish. It's very straightforward.
And for the win: Running Qwitter (finally!)
Once all of your dependencies have been installed, you are ready to run Qwitter. You can do this one of two ways:
Command Line
From the command line's opening screen, type: cd qwitter\src This will take you to the directory where all of Qwitter's source code resides. From there type: main.pyw Once that glorious "Welcome to Qwitter" message pops up, you're good to go!
Through Windows Explorer
Navigate to the folder where you installed Qwitter earlier, and enter the src directory. This is where all of Qwitter's source code resides. Activate the file labeled main.pyw, and wait for that "Welcome to Qwitter" message to appear.
Troubleshooting
The most common problem when running Qwitter from source occurs when updates require new or updated dependencies. In situations like this, Qwitter will not start, failing to throw any errors or tracebacks. Always run the update dependencies script located in the tools directory, to download anything new or updated.
