commit d1faa8aecb7693dd5d8d560adeb1c8930523835d Author: Tomás Touceda chiiph@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