[IGSTK-Developers] Continuing the discussion on main library-sandbox cross building

[David Gobbi]

Hi Andinet,

Using CVS branches to separate experimental code from production code is certainly the usual
approach for projects that use CVS.  A well-done sandbox should be easier to use, though.

I'm not saying that we should take the CVS-branch approach, but here are the two ways that it is
applied in VTK development:

1) The most common approach is not something that we should adopt for IGSTK: During what we call
the "Sandbox" phase, all code goes into the main branch.  Near to release time, a "Release" branch
is made for that particular release.  This doesn't match our existing review policies or check-in
restrictions at all, since any changes made during the "Sandbox" phase prior to the date when the
release branch was created are automatically included in the release branch.  

2) The "Experimental Branch" approach is more similar to what we do with the sandbox.  Each time
we start an "Sandbox" phase, we would make an Experimental branch off of the mainline.  Once the
code in the Experimental branch was reviewed, it would be merged into the mainline.  For IGSTK,
each Sandbox phase would require its own Experimental branch, and the Experimental branch would
have less-restrictive check-in policies than the mainline.  We would need to check with Andy to
see if it is possible to enforce branch-specific check-in policies, and how much work it would
take.

What we want to do with the sandbox is pretty much identical in function to the "Experimental
Branch" approach.  However, the Sandbox approach offers the following advantages:

1) It is conceptually simpler.  Many people have trouble with the CVS "branch" concept, with
differentiating "branch tags" from "non-branch tags", and with the arcane cvs commands needed to
access these features.  The idea of having a sandbox where the files in the sandbox trump files in
the IGSTK directory is very straightforward. 

2) If we use experimental branches, a branch has to be created each time we enter a new sandbox
phase.  The Sandbox is nice because it's always around.  If a sandboxed feature isn't ready for
release, we can just leave it in the sandbox until it is ready for a future release.

3) If a user wants to do their own experimental changes or additions to IGSTK, they can just make
a local copy of the sandbox to keep their changes separate from the main copy of IGSTK.  They can
even have their own sandbox on their own CVS server, if they so desire.  If we use experimental
branches, then only people with cvs write access to the main IGSTK repository will be able to make
experimental branches.

4) We already have a Sandbox.  Do we really want to shake things up by switching to experimental
branches?   When I first started with IGSTK I wondered "What's this Sandbox thing, and why don't
they use experimental branches?"  Well, the whole IGSTK development and review process revolves
around the Sandbox approach, so it seems best if we stick with it we want to keep moving forward.


Here's a straightforwad way that we can make the "skeleton copy" approach to the sandbox work with
CMake:

When "cmake" is run, as a first step it can merge the Sandbox and IGSTK into a third,
newly-created directory in the Sandbox build directory.  Then it would do the build there, and
there would be no INCLUDE paths to the original IGSTK or Sandbox directories.

The copying of all the files would be insignificant compared to the time required to compile them,
so it wouldn't significantly increase the build time.

The big issue is that debuggers would find the copies of the files, not the originals, and
developers would have to be aware of that fact.

In any case, I feel that we should continue with the Sandbox approach in one form or another.

 - David


--- Andinet Enquobahrie <andinet.enqu at kitware.com> wrote:

> As suggested by Stephen and David and as I agreed to later on,  we can 
> do the following for a main library-sandbox cross building.
> 
> 1) Make a skeleton copy of the whole main igstk library directory 
> structure to the Sandbox
> 2) As needed, copy main igstk library file to the Sandbox and modify it 
> ( either for a bug fix or feature add-on)
> 3) Modify the cmake file in the sandbox, so that a source and header 
> file list is created from modified main library files in the sandbox, 
> non-modified main library files in the main repository and new files in 
> the sandbox.
> 
> In implementing this cross-build system in my local machine. I run into 
> a problem of setting the include directory path.  It would be easier to 
> explain the problem with an example.
> 
> We have a new annotation class in the sandbox. To use this annotation 
> class,  new methods are needed in the "igstkView" class. Therefore, I 
> copied "igstkView" header and source files to the Sandbox and made 
> changes.  Therefore, cmake will pick the versions of the "igstkView.h" 
> and "igstkView.cxx" in the sandbox when generating the file list for 
> building the Sandbox.  We have "igstkView2D" class which is derived from 
> the "igstkView" class in the main repository. Therefore, we should be 
> able to invoke methods to handle annotations which are defined in the 
> base class ("igstkView") in "igstkView2D" class.. However, this fails 
> for the following reason. In building, the "igstkView2D" object file, 
> the compiler includes the "igstkView" class in the main library not in 
> the Sandbox.  This is due to the fact the igstk header files are all 
> included using double quotes  (""). When a header file is included in 
> double quotes, the compiler first searches for this header file in the 
> current directory before the -I include directory  path.  And we don't 
> want this. We want the compiler to search first for header files in the 
> Sandbox.
> 
> We (Luis and I)  thought of three solutions to work around this issue.
> 
> 1) Change #includes "*" to #includes <*> in all the files and add 
> sandbox before the main library to the Include directory list  (-I)
> 3) Copy all  files which have associations with the modified file to the 
> Sandbox. For example,  all derived classes if the base class is changed.
> 3) Copy all main library files  (both modified and non-modified ) to the 
> Sandbox and generate source and header file lists for building from  
> files in the Sandbox only.
> 
> The first option "seems" to work. Although, other unforeseen issues 
> might crop up when it is implemented. The second option seems to be 
> laborious and error prone. The third option will definitely work. It is 
> similar to how we are building the main library. The only issue is we 
> will be generating duplicate copies of files (both modified and 
> non-modified).
> 
> Contemplating on the third option, it made us think why we have separate 
> repositories for development and stable versions in igstk  And, in 
> devising ways of cross building between development and stable version, 
> we are manually mimicking cvs capabilities. Standard technique of  
> keeping the development version on the cvs trunk and stable versions of 
> the library on the branches might be a better option. It is something to 
> think about....
> 
> -Andinet
> 
> 
> 
> 
> 
> 
> _______________________________________________
> IGSTK-Developers mailing list
> IGSTK-Developers at public.kitware.com
> http://public.kitware.com/cgi-bin/mailman/listinfo/igstk-developers
>