Dev Adventures

Read Me First

2008-09-21T02:55:46Z

A book about writing style for technical documentation. !(Left)/dev-adventures-images/read_me_first.jpg!:http://www.amazon.com/gp/product/0131428993/ref=cm_sw_r_de_dp This book seem to cover many of the aspects specifics of our kind of "writing". We need to define a way to make everybody read the book!

Unit-tests Primer

2008-08-12T19:34:56Z

Unit testing is now a part of our development culture but there's much more than meet the eye in the subject. This article will expose some details of ESSS unit-test culture. h1. Module unittest p{color:red}. (short introduction of unittest module) h1. ESSS Extensions Short description of ESSS extensions on the original unittest modules. h3. Output Format We modified the original output format for tests: Before: bc. ok testPlatform (coilib50.platform._tests.test_platform.Test) Current: bc. ok coilib50.platform._tests_test_platform: Test.testPlatform h3. Color Output Show the test status (ok, error, fail) using colors. Green for "ok", yellow for "fail" and red for "error". h3. TODO methods Using the prefix @todo@ in a method instead of @test@ mark it as a TODO. That means that the test will not break a project continuous build if it fails. h3. Test case for GUI The GUITestCase, located in the xgui20 project, serves as a base class to test GUI elements using Qt. h3. runtests Runtests is a command line tool that executes tests found in a python path. The tests package must be importable by python (that means that it must have an @__init__.py@ file) h3. Data directory Create a directory that starts with "test_XXX" and it will generated a "data_XXX.py" file with its contents zipped. p{color:red}. Extend this explanation !!! Remarks: Do not add a __init__.py module inside the test_XXX directory or else python will import the test_XXX instead of the test_XXX.py. h1. ESSS Organization p. How the unit-tests are organized in ESSS projects and applications. h2. Code conventions Always use a ETK @unittest@ module. Do not use the python's original @unittest@ module bc. from coilib50 import unittest p(rationale). Rationale: The output format of our unit-test classes differs from the original, so mixing unit-test classes will generate mixed output format. h2. Naming conventions h3. UT001 - Sub-package: _tests The tests of a given package are placed in a sub-package called @_tests@. bc. \coilib50\basic\_tests p(rationale). Rationale: The tests module is not an usual module but a "protected" module and the prefix signalizes that. Using the underscore as a prefix makes it easier to find it in a big list of packages (directories). h3. UT002 - Module: test_XXX.py The tests modules filenames have the @test_@ prefix, and follow the module naming standards: lowercases with underscores. The preffix @test_gui_@ is now deprecated and must be removed. bc. test_platform.py p(rationale). Rationale: Using a standard name for test modules makes it easier to find them. The @runtests@ tool requires this standard in order to conside the module a test. h3. UT003 - Test class name: @Test@ Each module should have only one TestCase instance that must be named simple "Test" bc. class Test( TestCase ): If you need to declare more than one test module for a given module, suffix it with a sequencial number or another string to tell them apart. bc. test_alpha_1 test_alpha_2 bc. test_alpha_initialization test_alpha_view p(rationale). Rationale: We already have a lot of information about the test from the test package and method. There is no use to another layer of information in the test-case class. h3. UT004 - Test methods: testXXX The test methods declared in the test-case have following the "mixed" case: bc. testPlatform h3. UT005 - Test documentation for mantis The documentation for a test of a mantis entry must be the mantis number and description as found in the mantis database: bc. ''' 0010885: Show current time value ''' h2. Utilities symbols Often when creating a test we need to define auxiliary symbols such as variables, classes and functions: h3. UT006 - Declare on test: prefix @"_"@ When declaring a symbol other than the test-case use a underscore as a prefix. p(rationale). Rationale: This avoids the automatic import feature of PyDev to try to import a symbol defined in a test module. h3. UT007 - Reusable symbols for tests: @unittest@ module If you have a symbol that can be reusable in other tests, create an @unittest@ module and place the symbol there. h3. UT008 - Reusable symbols for tests: prefix @"My"@ or @"Dummy"@ When declaring a reusable symbol, in a @unittest@ module, use the @"My"@ or @"Dummy"@ prefix. In this case there is no need to prefix with "_" as when declaring the symbol in the test module. p(rationale). Rationale: This provides a clear way to identify a test symbol that is not part of the project. h2. Tips and Tricks h3. Using unittest module p{color:red}. Always import the unittest module instead of the inner symbols. h3. Runing only one test in eclipse Use the @sys.argv@ attribute to change the command line parameters to the unit test execution. You can pass any command line accepted by the test itself, such as "-v" to a verbose output. bc. def __name__ == '__main__': import sys sys.argv = ['','Test.testPlatform'] unittest.main() h1. Thanks Thanks to Ari and Menegazzo for promptly reviewing this article.

Configure errors

2008-07-03T20:09:17Z

Errors found while running "configure" script to build dist for unix systems. The first solution for this one was to remove the @GCC_ROOT@ environment variable. But we have place it back because GCC uses it to find it's friends (@cc1@) The solution was to set the environment variable @C_INCLUDE_PATH@ to a directory that includes "limits.h" inside the gcc binaries itself. Since we are using an alternative layout for GCC, we must use three (until now) environment variables to change the compiler location: * @GCC_ROOT@ * @C_INCLUDE_PATH@ * @CPLUS_INCLUDE_PATH@]]>

Adding third party libraries to dist (part 1)

2008-06-25T14:24:02Z

A guide on how to add a third-party library in the dist. Third Party libraries are libraries whose code is not developed by ESSS. We call these libraries shared-resources because they are shared amongst the projects. The group of libraries that work well together are organized in a **toolchain**, that is, a list of shared-resource versions compatible with each other. The toolchains are named after the **dist** project, which organizes these different libraries together building a "dist", or distribution. This article provides a guideline on how to add new libraries to the distribution, from the initial tests with the library to the integration of the build process. h3. Considerations As a rule, third-party code should not be included in the "projects-repository". That means that code that is not developed by ESSS should not be incorporated in the ESSS projects. The right place for these libraries is the "shared-repository", where both the source-code and binary code for the various platforms are stored. The shared-repository is source of the libraries downloaded by the famous builds command **bb update.download**. This separation make possible to update the third-party library without having to change the project that uses. Beyond that, other applications can use the trird-party library without having to depend on the project that originally added it to the dist. h3. Initial Tests The first step towards the incorporation of a new library in the distribution is to test it by using it. Once the library is found the user should compile and organize it locally as if it were already in the distribution, that means: h4. 1. The library must be placed in the "Shared" directory p. The name of the directory must use the naming stardard for the shared-resources, that is: the name is lowercase and the library version separated by a hipen: h5. Examples: * @e:\Shared\dist-0707\i686.win32\boost-1.34.0@ * @e:\Shared\dist-0707\i686.win32\pywin32-211@ * @e:\Shared\dist-0707\i686.win32\jpeg-6b@ p. Note that the version format follows the original version standard adopted by the third-party library. h4. 2. The library directories p. Try to follow the original directory organization. If there is no suitable organization, or the original organization is too messy, make sure to include the following directories: * @/include@ Place for the C++ include files * @/bin@ Place for executables and DLLs * @/lib@ Place for the libraries (not the DLLs) * @/python@ Place the python code here h4. 3. The project that uses the library must include it using a shared-script. p. The shared-script is a python script that holds all the information about a given shared-resource or project. In order to use the third-party library you must create a shared-script for it. Initially place the script in the @/build/SharedScript@ folder of your project. Later the shared-script will be incorporated in the Builds' shared-scripts. p. The following template can be used for the library shared-script. It is declared for a library "mylib" with the version "0.1". p. "mylib.py":http://www.cantovirtual.com.br/dev-adventures-images/mylib.py p. Note that the file must be named after the library, in this case, "mylib.py".

_except_handler4_common

2008-06-09T13:57:49Z

p=. !(Center)/dev-adventures-images/_except_handler4_common.png! "The procedure entry point _except_handler4_common could not be located in the dynamic link library msvcrt.dll" The error above occurs when running the latests version of Builds when trying to download stuff. h3. The problem The file *mswsock.dll* is included in the binary distribution of Builds when it should not. This is happening because we now are building Builds from a Vista machine, not from a Windows XP. For some unknown reason py2exe adds the file witch is not compatible with XP systems. h3. The solution Remove *mswsock.dll* from the distribution.

Book Meeting - Peopleware Chapter 3

2008-06-04T15:56:54Z

Highlights of chapters 3 of Peopleware for the Book Meeting of 4.jun.2008. h3. Vienna Waits For You Spanish Theory Management And now a word from the home front There aIn't no such thing as overtime Workaholics Productivity: Winning battles and losing wars Reprise

The order of libs matter in GCC

2008-05-29T20:32:50Z

The order of the libraries in a link command line makes difference when compiling using GCC. Differently from Windows, the list of linking libraries must be in the descend order of dependency, that is, the most dependent first and the less dependent last. Our construction mechanism keep the order of the list defined in the SConstruct, so, keep the libraries in the correct order there.

Book Meeting - Peopleware Chapter 1,2

2008-05-28T15:49:13Z

Highlights of chapters 1 and 2 of Peopleware for the Book Meeting of 28.may.2008. h3. Chapter 1 - Somewhere today a project is failing Software development is about people, not technology. Managers need to change the mindset to put the focus in the right place. Most project failures are because of "politics", not technology. "The light is better here" h3. Chapter 2 - Make a cheeseburger, sell a cheeseburger Software development is not a production line and should not be treated as such. h4. A Quota for Errors The job at hand can gain on errors. We must have an environment that accepts them. h4. Management: A Bozo definition: We must encourage people to work, not "kick asses". Brute force does not work for people who have to use their brains in the work. h4. The People Store People a not replaceable. h4. The Project in Steady State Is Dead A project is in constant flux with new solutions and problems arising all the time.

Updating time with localroot

2008-04-22T13:54:20Z

Ben (the server machine) wasn't using the correct time and every time we try to update it generates the following error: bc. System error 5 has occurred. Access is denied. This will make it prompt for a password, and more important, register you as a valid user for the time updating command: bc. net time \\ironman h3. References: * http://www.zotline.com/shownote.zot/NoteNum/4429.html]]>

Introducing vector grid-functions

2008-04-17T15:40:07Z

The implementation of vectorial grid-functions in Sci.App changes several places in the process hierarchy. This article explains each change, including the decisions made during the process. h3. Basics Vectorial grid-functions will be considered as a group of grid-functions. This made it easier to obtain each component separately. The affected classes in the process hierarchy are: * Reader: The reader must be able to generate groups. The PhonyReader will be able to simulate a vectorial grid-function (Velocity) for test purposes. * Source: The source-process must implement the QUERY_GRID_FUNCTIONS query properly to consider the grid-function groups. Also, the request mechanism must be able to add the grid-function in the generated output. h3. Reader The phony-sample-reader will add Velocity grid-function group to its collection of grid-functions. h3. Source Added two new variables to describe a grid-function: *component* and *source*. h4. component * scalar: A grid-function composed by one scalar for each "cell". This is what exists today. * vector: A grid-function composed by N scalar grid-functions, where N is the number of geometry dimensions. The value of N is 3 for Kraken. * component: The grid-functions that compose a group grid-function (either vector or any other kind) are not listed as "scalar". They are listed separately as "component", which means that their also available inside a grid-function group. * tensor: A grid-function that represents a tensor. Not used for now. h4. source * loaded: The grid-function is loaded from a file, using the reader * generated: The grid-function is generated, based on loaded grid-functions. Currently we have two kinds of generated grid-functions: transported and magnitude. h3. GridFunctionKey The GridFunctionKey stores information sufficient to identify a grid-function.

Adding a project in CruiseControl

2008-04-15T14:16:08Z

This article enumerates the steps and problems found while adding the pwda11 project to our cruise-control. h3. Prerequisites Download the project and add it in the shared-scripts-path bc. bb config.auto_shared_scripts x: ii . h3. New install procedure The first step in order to place a project in the cruise-control it's to implement the "Procedure_Install" in its shared-script. This procedure replaces the "install.py" installing process. The new install process is the default method for projects in CruiseControl. bc. bb shared.pwda11 install h3. Check svn:ignore consistency The files in the repository must not match any svn:ignore mask. To check this you must delete all the svn ignored files using the following command: bc. bb svnignore.clear x:/pwda11/source/python Then, you must check if any repository file was deleted using the "st" svn command: bc. svn st x:/pwda11/source/python No files should be missing from the repository. If it is, its because the svnignore.clear removed it. You must either change the svn:ignore to no longer match the repository file or change the file name. h3. svnignore.txt The file svnignore.txt is placed in the python source directory of the project. This file holds the value of the svn:ignore property for all the source\python directory. To apply the value use the command: bc. svn propset svn:ignore \ -F x:\pwda11\source\python\svnignore.txt \ -R x:\pwd11\source\python h4. NOTE Avoid setting the svn:ignore property on install procedure. It's better to do it manually for each new directory to double-check for consistency.

Micro-instrument

2008-04-09T15:30:18Z

The current implementation of XGUI is heavily based on an concept called Instrument. This concept dates from the first XGUI versions, and have not evolve since them. Now, with a lot of implemented features we find out that this concept must be reviewed and updated. h3. The original concept Originally the Instrument is a wrapper class that provides two methods: Get and Set. It's purpose is to encapsulate a widget or any other data and provide a simple and uniform interface to obtain and change a value. Together with these methods, we also have the Connect/Disconnect methods, that provide a way to listen to changes on the instrumented object. Quite simple. Based on this design, all we have to do to connect a widget to an object attribute for example, is to create a instrument for each and then connect these instruments using the predefined interface. This connection is done by the "Musician", which holds two instruments and perform this connection. h3. The reality The problem is that we don't want just the single, simple, unique value from the widget. We want more. We want to change its color. We want to change its enabled and visible states. We want to fill a list-widget values. In short, there is a lot of stuff to connect in a widget. The solution implemented for this complexity was to extend the Instrument, creating an instrument for each widget and adding to its interface the necessary callbacks and attributes. For instance, the combo-box instrument have values (SetValues/GetValues) attribute which determines the list of values. All the widget instruments have the visible (SetVisible/GetVisible) and enabled (SetEnabled/GetEnabled) attributes to handle its visible and enabled states. In short, we kept the idea of one instrument for each widget and added more and more features to each widget as needed. !{align:center}/dev-adventures-images/micro_instrument-current.jpg! h3. The new concept The new concept, called micro-instrument, determine that each separate feature is implemented by a different instrument. In the sample above, we would have an instrument for the current value of the combo-box, one to update the combo values, one for its visible state and other for its enabled state. Each instrument works with only one attribute, implementing the Set/Get interface. To fully configure a widget, we'll use several instruments and associated musicians, one for each feature. !(center)/dev-adventures-images/micro_instrument.jpg!

Translation Files

2008-04-01T13:39:34Z

The automatic build fails because there's a modification in the source files. This modification is in the translation file (pt-BR.ts). The file generated by the install process differs from the one in the repository. 2. Edit the translations bc. linguist]]>

The dark side

2008-03-14T14:18:22Z

The new monitor have a very strong white that was bothering my eyes. So I've decided to switch the color-scheme to darker one. !/dev-adventures-images/the_dark_side.png!

Automatically install projects

2008-02-12T16:24:38Z

Currently, builds is able to download a compiled and tested version of all our libraries (ETK) using a simple command. But this is not enough to make the libraries usable, the user must first "install" these libraries. How can we automate this process too? h3. The simple solution p. The simplest solution is to call "_install.py_" script, as done manually using the command line. These script would be called from inside the builds command "project.update" for each updated project. The call would be done by calling the "System" or "Python" toolbox methods. h3. Considerations over the simple solution p. This solution is very straight forward and easy to implement but does not take into consideration a design premise, or ideal, of Builds: p. We wanted to place all project information into a unique file (shared-script). p. The information about how to "install" the library is currently in a totally independent script, placed in a directory that is not available in the python namespace. It works fine until now. p. Now we want that a command in the "shared-script" namespace execute the algorithms implemented in the _install.py_ script. For me, this is clear sign that it's time to review the _install.py_ script implementation, merging it with the shared-script. h3. Install in the shared-script p. Most _install.py_ scripts are very simple, since they inherit most of its implementations and need only to configure some parameters. p. The implementation of install in the shared-script (Procedure_install) would use in the base class for code generation, but which code-generator to use and all the project information (name, directories) would be obtained from the shared-script itself, that already have some (if not all) the information needed by the code-generators. p. Being a shared-script command, such a the "download" procedure used by the "bb project.update", the "install" procedure would be used to create a "bb project.install" or even be called in "project.update" itself. All these algorithms would be working in the same way and all the project related information (including how to install it) would be centralized in one place: the shared-script. h3. SConstruct p. The SConstruct have a lot of similarities with the _install.py_ script. It is placed in the same directory. Has python code in it. Is called in the project construction process. But, differently from the _install.py_ script, the SConstruct acts as a bridge between the SCons tool and our repository of project information (shared-scripts). p. The _install.py_ script in the other hand, acts completely aliened from the shared-scripts, many times replicating some information available in the shared-scripts.