[tor-commits] [vidalia/alpha] Write Getting Started tutorial

[chiiph at torproject.org]

commit d1faa8aecb7693dd5d8d560adeb1c8930523835d
Author: Tomás Touceda <chiiph at torproject.org>
Date:   Mon Apr 9 21:59:56 2012 -0300

    Write Getting Started tutorial
---
 changes/bug2925         |    3 +
 doc/getting-started.txt |  397 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 400 insertions(+), 0 deletions(-)

diff --git a/changes/bug2925 b/changes/bug2925
new file mode 100644
index 0000000..350b802
--- /dev/null
+++ b/changes/bug2925
@@ -0,0 +1,3 @@
+  Internal cleanups and improvements:
+  o Document how to get started with Vidalia development in a tutorial
+    fashion. Fixes bug 2925.
\ No newline at end of file
diff --git a/doc/getting-started.txt b/doc/getting-started.txt
new file mode 100644
index 0000000..26889b8
--- /dev/null
+++ b/doc/getting-started.txt
@@ -0,0 +1,397 @@
+== Getting started with coding for Vidalia ==
+
+=== Sections ===
+ * Foreword
+ * Dependencies
+ * Building plain Vidalia
+ * How to build some of its optional features:
+  * Building with Marble
+  * Enabling plugin support
+ * Code structure
+ * Contributing workflow
+
+=== Foreword ===
+
+Vidalia has a stable and an alpha branch. The stable branch is
+actually called master in the source code repository. The stable
+branch will have bugfixes and new features when these demand being
+released as stable for the sake of the users. Most of the information
+in this document applies to all Vidalia branches and released
+versions, in case there is a specific issue that applies from a
+specific version or on a specific branch, it will be specified
+explicitly.
+
+This is not a Git tutorial, for that there are really good references
+already online. I particularly recommend the online (and paperback)
+book ProGit.
+
+Vidalia can be built for most flavors of BSDs too. They should be
+similar to the references to Linux, but we do not support actively any
+of them. That being said, if you find a bug. that does not mean we
+won't fix it. It means that we are not building Vidalia on, say,
+FreeBSD every day.
+
+=== Dependencies ===
+
+The most important (and the basic) dependencies to build Vidalia are:
+Qt >= 4.7.4 and CMake.
+CMake should be installed as a regular application for every OS. Qt on
+the other hand can be used in several ways, the most important thing
+to understand is that you need to let CMake know the path to the tool
+named qmake from the Qt toolkit, and based on that it should be able
+to figure out the rest of the paths. If that fails, we will explain
+how to solve it later on. We will use the terminal to build Vidalia
+and explain how to do the different things we are going to cover in
+this document.
+
+If you use Linux you will have easy access to a terminal. If you use
+Windows, on the other hand, what I use is msysGit[1] (especially since
+we will use Git for a lot of things explained later on this document).
+If you are an OSX user, you should use Terminal.app.
+
+To manage the source code, Vidalia (and all the Tor Project projects)
+use Git[2]. You should install it with your preferred package manager
+if on Linux, use msysGit on Windows, or use MacPort or Homebrew on
+OSX.
+
+Vidalia has a lot of optional features that can be enabled or disabled
+in the configure stage (see section Building plain Vidalia). Among
+these possibilities, Vidalia can use Marble widget[3], which is a map
+widget to display nodes around the world in the Network Map. You
+should clone Marble's repository (which also uses git) if you want to
+build with Marble support (see section Building with Marble), but it
+is not mandatory.
+
+Another optional feature is Google Breakpad, which we won't get into
+details here, but you should be able to enable it based on how you
+enabled Marble, and the README.breakpad guide.
+
+If you are running the alpha branch (or release >=0.3.1), another
+dependency will be qtscriptgenerator. We will get into details for
+this in the section Enabling plugin support.
+
+=== Building plain Vidalia ===
+
+Building Vidalia is quite simple if you know the few steps you should follow.
+Assuming you have installed Qt, locate the qmake binary. We will
+denote this path as $QMAKE_BIN.
+
+After that, you should clone Vidalia's source code repository:
+
+{{{
+$ git clone https://git.torproject.org/vidalia.git
+}}}
+
+This will create a directory called vidalia. If you want to use the
+alpha branch, you should do the following:
+
+{{{
+$ cd vidalia
+$ git fetch origin
+$ git checkout alpha
+}}}
+
+From this point we will start using CMake. This tool has the
+peculiarity that you can have a separate directory to build your code,
+so that all the object code and other auxiliary files do not get in
+the way of your implementation. So we will use a directory named
+"build" inside Vidalia's root:
+
+{{{
+$ mkdir build
+$ cd build
+$ cmake .. -DQT_QMAKE_EXECUTABLE="${QMAKE_BIN}"
+}}}
+
+The cmake .. command directs cmake to where the code repository is,
+and also sets the variable QT_QMAKE_EXECUTABLE. If CMake complains
+about other variables not being set, you should set them similarly to
+the one we are already setting.
+This last step is called the configuration step (or phase).
+
+After this, we start the actual building phase:
+
+{{{
+$ make -j4
+}}}
+
+The number you would use for the -j parameter should be number of
+cores +1 (unless you want to wait longer for the build, in which case
+you can just ignore the parameter completely).
+
+If everything goes alright, you should have the Vidalia binary inside
+the path: build/src/vidalia/. If you are on Linux it will be called
+vidalia, vidalia.exe on Windows, and Vidalia.app on OSX. You can run
+Vidalia with the following parameters (assuming you are on Linux, it
+will be similar in the rest of the OSs):
+
+{{{
+$ ./src/vidalia/vidalia --loglevel info --logfile /dev/stdout
+}}}
+
+=== How to build some of its optional features ===
+
+==== Building with Marble ====
+
+To build Vidalia with Marble support, you should clone and build
+Marble from git[5] with Qt-only support.
+
+We will assume that your marble clone is located in ~/marble, your
+build directory is located in ~/marble/build.
+
+Once we reach this point, we can configure Vidalia to use Marble with
+the following command (from Vidalia's root):
+
+{{{
+$ cmake -DUSE_MARBLE=1 \
+        -DMARBLE_INCLUDE_DIR=~/marble/src/lib \
+        -DMARBLE_DATA_DIR=~/marble/data \
+        -DMARBLE_LIBRARY_DIR=~/marble/build/src/lib \
+        -DMARBLE_PLUGIN_DIR=~/marble/build/src/plugins ..
+}}}
+
+When the configuration has finished, you can compile Vidalia as usual:
+
+{{{
+$ make -j4
+}}}
+
+Remember that the -j parameter is something you should figure out for
+your system or just leave it out completely if in doubt.
+
+==== Enabling plugin support ====
+
+Vidalia >= 0.3.1 has support for plugins. How plugins are structured
+and how they work will be covered on another document, but to actually
+work with plugins we need to be able to build qtscriptgenerator[4].
+
+To build it, you should follow its README, but the following hints
+might come handy if you get stuck:
+
+ * On Windows, you may need to execute the following to get the
+generator to locate Qt's headers:
+
+{{{
+   setx QTDIR /c/QtSDK/Desktop/Qt/4.7.4/mingw/
+}}}
+
+Note that the path may change depending on your Qt installation.
+
+ * On OSX we build this the following way:
+
+In the file qtbindings/qtscript_uitools/qtscript_uitools.pro, change this:
+
+{{{
+CONFIG += uitools
+}}}
+
+to this:
+
+{{{
+CONFIG += uitools plugin link_prl
+}}}
+
+And then follow these steps:
+
+{{{
+$ cd path/to/generator/
+$ qmake -spec macx-g++
+$ make
+$ ./generator
+$ cd ../qtbindings/
+$ qmake  -spec macx-g++ -recursive
+$ make release
+}}}
+
+=== Code structure ===
+
+Vidalia is separated in several modules, here is a brief explanation
+of each directory:
+
+{{{
+src/
+  All the source code is located in this directory.
+
+src/vidalia/
+  Main module, this is where Vidalia's GUI files are located, the main
+window classes are right there, other parts of Vidalia that take
+several files are located in their own submodule inside this one.
+
+src/vidalia/about/
+  The About and the License dialogs are located here.
+
+src/vidalia/bwgraph/
+  The Bandwidth Graph classes are here.
+
+src/vidalia/config/
+  In this directory all the configuration classes are located.
+
+src/vidalia/help/
+  The help browser and the actual help content is located in here.
+
+src/vidalia/i18n/
+  Here we have all the files used for translations.
+
+src/vidalia/log/
+  The Message Log code is located in this directory.
+
+src/vidalia/network/
+  Here you can find the Network Map code. Here lives the code that
+also handles Marble.
+
+src/vidalia/res/
+  All the different resources like icons or certificates are in this directory.
+
+src/common/
+  The common module has somwhat generic classes and functions used in
+other modules.
+
+src/crashreporter/
+  Here you can find the code that interacts with Google BreakPad.
+
+src/miniupnpc/
+  Miniupnpc is a UPNPC library that Vidalia bundles in its code to
+build it with CMake, but it is not an code that is maintained by us.
+
+src/tools/
+  Inside this directory you can find self contained simple
+applications that are used for different purposes, like translating
+from different translation file types.
+
+src/torcontrol/
+  This is the most important module that handles the interaction
+between Tor and Vidalia.
+
+changes/
+  In this directory live the different changes introduced by a branch
+that has been merged, its contents will go to the CHANGELOG file. See
+the Contributing workflow section for more information.
+
+cmake/
+  This directory contains the CMake macros used by Vidalia's build scripts.
+
+contrib/
+  In here you can find some GeoIP scripts.
+
+debian/
+  This directory contains some Debian specific information.
+
+doc/
+  This one contains some documentation regarding Vidalia's design and
+Doxygen configuration.
+
+pkg/
+  This directory contains the scripts used for packaging on different
+formats, like app for OSX, rpm for Linux and a Windows installer.
+}}}
+
+=== Contributing workflow ===
+
+There are at least two different ways to contribute to Vidalia in
+terms of how you submit your changes. The first approach might be
+simpler than the second, but the one you choose depends on how you
+will get involved.
+
+NOTE: There are several ways of doing what is proposed, we will not
+get into details, each person should adopt the way suits them best.
+
+==== Submit a patch ====
+
+Vidalia uses git to manage its source code, as we explained before.
+Git has a nice feature called format-patch. Here's how it works:
+
+ * Update the repository to its latest version. You should replace
+master with the current branch you are working on
+
+{{{
+ $ git pull origin master
+}}}
+
+ * Edit the code as you see fit
+
+ * Add the files you want to be in the patch you will submit
+
+{{{
+ $ git add file1 file2
+}}}
+
+  * Create a commit
+
+{{{
+  $ git commit -m "Some commit message that represents the changes"
+}}}
+
+  * And then we create the patch:
+
+{{{
+  $ git format-patch HEAD..HEAD~1
+}}}
+
+Why not just create the patch with diff? This way you will be in
+charge of the actual commit (you will be the committer). Another added
+value is that you can make several commits, if it makes more sense for
+your code. Otherwise, the person that will push the new code has to
+handle all themselves, and it may not be what you'd have done (even
+though the final code will be the same).
+
+==== Create a branch ====
+
+The ideal way to contribute is to have a remote somewhere (github,
+gitorious, etc), and point us to a branch in that remote. The branch
+should be named bugXXXX_sometext, where XXXX is the ticket number, and
+sometext is a representative text for the code in that branch.
+
+When the branch is reviewed, it will be merged to its base branch and
+pushed to the official Vidalia repository.
+
+The review process varies with each fix or person that is involved,
+but there are some basic guidelines that you should follow to make the
+procedure as fast as possible.
+
+===== Changes file =====
+
+Each Vidalia release has its own portion of the CHANGELOG. This
+CHANGELOG is built from a series of changes files. These files are
+located in the "changes" directory. Their basic structure is the
+following:
+
+{{{
+  <Category>:
+  o <Text that describes the change>. [Fixes bug | Resolves ticket]
+<ticket number>.
+}}}
+
+The valid categories are:
+
+ * New features
+ * Bugfixes relative to Vidalia 0.2.x
+ * Bugfixes relative to Vidalia 0.3.x
+ * Internal cleanups and improvements
+
+The decision whether to use "Fixes bug" or "Resolves ticket" should be
+determined by the nature of the issue. If it was a bug, it should say
+"Fixes bug", and if it's a ticket for a new feature, it should say
+"Resolves ticket".
+
+Each branch must have their own changes file, this way when it is
+merged it will add the file to the changes directory in the base
+branch.
+
+===== Commit structure and code guidelines =====
+
+A fix branch (or format-patch) should separate a fix into several
+relevant commits, especially if the fix is a big one and can be
+devided (there are exceptions to this rule).
+
+In terms of coding guidelines, code that does not follow the
+guidelines specified in the HACKING document won't be merged. You can
+find this document in the root directory of your cloned Vidalia
+repository.
+
+--
+
+[1] http://msysgit.github.com/
+[2] http://git-scm.com
+[3] http://edu.kde.org/marble/
+[4] https://qt.gitorious.org/qt-labs/qtscriptgenerator
+[5] http://edu.kde.org/marble/obtain.php