~ubuntu-branches/ubuntu/trusty/rheolef/trusty-proposed

@c =========================
@chapter FAQ for developers
@c =========================
@cindex FAQ

This list of Frequently Asked Questions intended
for Rheolef developers and maintainers.
I'm looking for new questions (@emph{with} answers,
better answers, or both.
Please, send suggestions to
@email{Pierre.Saramito@@imag.fr}.

@c -----------------------------------------------
@section How to regenerate the @code{configure} script
@c -----------------------------------------------

@toindex @code{automake}
@toindex @code{aclocal}
@toindex @code{autoconf}
@fiindex configure.ac
@fiindex Makefile.am
@fiindex acinclude.m4

The configure script and makefiles are automatically
produced from file @file{configure.ac} and @file{Makefile.am} 
by using the autoconf and automake commands. Enter:

@example
	bootstrap
@end example

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
@subsection In which order does the things build ?
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

Let us look at with details the configure files flow:

@example
[acinclude.m4] -----> aclocal* -----------> [aclocal.m4]

[configure.ac] -+
----------------+---> autoconf* ----------> configure
[aclocal.m4] ---+

[Makefile.am] ------> automake* ----------> Makefile.in

[config.h.in] -+                        +-> config.h
               |                        |
Makefile.in ---+----> configure* -------+-> Makefile
               |                        |
[config.mk.in] +                        +-> config.mk
@end example

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
@subsection What means these commands ?
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

Let us review the list of commands:

@table @code
  @itemx aclocal
	take @file{acinclude.m4} and build @file{aclocal.m4}.
   	The arguments specifies that these files are located
   	in the @file{config/} directory.

  @itemx automake
	translate every @file{Makefile.am} and then build a @file{Makefile.in}. 

  @itemx autoconf
	 translate @file{configure.ac} in
   	@file{configure} which is an executable shell script.
   	The arguments specifies that @file{aclocal.m4} is located in the
   	@file{config/} dirctory.
   	All this files are machine independent.

   @itemx configure
	the automatically generated script,
   	scan the machine and translate @file{config.h.in}, @file{config.mk.in}
   	and every @file{Makefile.in}
   	into @file{config.h}, @file{config.mk} and every @file{Makefile}, respectively.
   	At this step, all produced files are machine dependent.

@end table
@c ----------------------------------------
@section How to save my version ?
@c ----------------------------------------

First, check that our distribution is valid
@example
        make distcheck
@end example

First, check that your modifications are not
in conflict with others.
Go to the top source directory and enter:

@example
	make status
@end example

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
@subsection Easy: no conflicts with another developer
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

A listing of labeled files appears:

@example
	Modified                skit/lib/blas1_tst.c
	Update                  skit/lib/blas2_tst.c
@end example

Its mean that you have modified @file{blas1_tst.c}.
Another concurrent developer has modified @file{blas2_tst.c},
and your local file version is not up-to-date.
There is no conflict, labeled by a @code{*Merge*} label.

First, update your local version:

@example
	make update
@end example

Before to store your version of the Rheolef distribution,
check the consistency by running rnon-regression tests:

@example
	make distcheck
@end example

When all tests are ok:

@example
	make save
@end example

and enter a change log comment terminated by the
@code{ctrl-D} key.


Check now that your version status is the 
most up-to-date Rheolef distribution:

@example
	make status
@end example

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
@subsection I have conflicts with another developer
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

The listing issued by @code{make status} looks like:

@example
	Modified                skit/lib/blas1_tst.c
	Update                  skit/lib/blas2_tst.c
	*Merge*                 skit/lib/blas3_tst.c
@end example

Its mean that you and another developer have 
modified at least one common line in
@file{blas3_tst.c}.
Moreover, the developer has already saved his version
in a previous Rheolef distribution.
You have now to merge these modifications.
Thus, enter:
@example
	cd skit/lib
	mv blas3_tst.c blas3_tst.c.new
	cvs checkout blas3_tst.c
	sdiff blas3_tst.c blas3_tst.c.new | more
@end example
and then edit @file{blas3_tst.c} to integrate the
modifications of @file{blas3_tst.c.new}, generated by
another developer. When it is done, go to the top directory and enter,
@example
	make status
@end example
It prints new:
@example
	Modified                skit/lib/blas1_tst.c
	Update                  skit/lib/blas2_tst.c
	Modified                skit/lib/blas3_tst.c
@end example
The situation becomes mature:
@example
	make update
@end example
It will update the @file{blas2_tst.c}.
Finally,
@example
	make save
@end example
that will save modified @file{blas1_tst.c} and @file{blas3_tst.c}.

@c PRCS implementation
@c @example
@c 	prcs merge
@c @end example
@c 
@c @code{prcs} will prompt you for files in evolution.
@c When there is a merge, you can print differences 
@c `@code{d}'
@c and creating an anotated file 
@c `@code{m}'.
@c Then edit these anotated files and performs merges.
@c For more informations about the @code{prcs} program,
@c see the corresponding documentation 
@c at @url{http://www.XCF.Berkeley.EDU/~jmacd/prcs.html}.
@c  
@c When you have scanned all concerned files,
@c enter @code{make status} and no more
@c @code{*Merge*} label may appear.
@c Thus, you can 
@c save our version as in the previous paragraph.
@c 
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
@subsection I have deleted a source file...
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

@toindex @code{make}
@toindex @code{cvs}
@cindex version management

I have entered:

@example
	rm Makefile.am
@end example

...aie !

How to restaure the file, now ?

Enter:

@example
	cvs checkout Makefile.am
@end example

You restaure the last available version of
the missing file in the most up-to-date 
Rheolef distribution.