[task #15813] book: Add a `developer-build' example in the `Developer' section

[Pedram Ashofteh Ardakani]

URL:
  <https://savannah.gnu.org/task/?15813>

                 Summary: book: Add a `developer-build' example in the
`Developer' section
                 Project: GNU Astronomy Utilities
            Submitted by: pedram
            Submitted on: Thu 19 Nov 2020 05:47:36 PM UTC
         Should Start On: Thu 19 Nov 2020 12:00:00 AM UTC
   Should be Finished on: Thu 19 Nov 2020 12:00:00 AM UTC
                Category: Book
                Priority: 5 - Normal
              Item Group: Documentation
                  Status: None
                 Privacy: Public
        Percent Complete: 0%
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
                  Effort: 0.00

    _______________________________________________________

Details:

While tinkering with the CosmicCalculator program, I realized the need to test
if the changes work as expected and did not sabotage any of the other parts.

Fortunately, the `Gnuastro' team has developed automatic and smart tests. But
I couldn't find a step by step example to ease the process. So, I asked and
Mohammad emailed me a kind and generous reply.

We thought we should put the reply into the documentation! So, with this new
task, we'll try to add a step by step example to the `Developing' section of
the documentation to make things easier to follow.

With Mohammad's permission, you can find a part of his helpful reply below:

= Mohammad's reply: =

[... Truncated Text ...]

When you build Gnuastro with the  './developer-build' script, the
project does indeed get built in a directory in RAM called
'/dev/shm/gnuastro-XXXX'. But there is an easier way to access that
location ;-)! Just look at the newly built 'build' directory in the
source. Its actually a symbolic link to that '/dev/shm' directory. To
confirm, run 'ls -l' in the top source.

By the way, the 'developer-build' script will automatically find the
number of threads on your system, so you don't need the '-j4' :-).

So to test any Gnuastro program during the development, you need to
directly call the build executable with its full address relative to
where you are running (or its absolute address).

For example to test your CosmicCalculator program, you can run this
command from the top of your source directory:

./build/bin/cosmiccal/astcosmiccal --version

You will notice that the version is more recent than the one you already
have on your system (in case you didn't install from the temporary
directory)

astcosmiccal --version

But it will be very annoying to give that full address! So to test
programs during development, I have written a high-level script in
'tests/during-dev.sh'. It is heavily commented, so if you read through
those comments things should become clear for you.

Here is a cheat-sheet of what I do with 'tests/during-dev.sh':

1. I have a 'tmp' directory in my home directory for temporary outputs
(like the outputs of programs I am busy developing). Since you will also
start playing with data during development, its good to have such a
temporary directory for tests. So I set '~/tmp' as the value of 'outdir':

outdir=~/tmp

This 'outdir' is mandatory! If you don't specify it the script will
complain and abort.

2. In the 'utilname' variable, you should put the name of your desired
program without the starting 'ast'. So if I wanted to test your
scenario, I would set:

utilname=cosmiccal

'utilname' is also mandatory and without it, the script will complain
and abort.

3. The "arguments" to the program (usually data file names) should be
given in the 'arguments' variable. But this is optional and in your
scenario, you don't need it. So you can just leave it without a value.

4. The "options" argument is for the command-line options (that start
with one or two dashes: '-' or '--', like '-P' or '--printparams'). So
in your scenario, you can put below. The reason I am putting double
quotations is because you will soon start to add more options during
your tests, and if you want to pass a SPACE character into the variable
value, you need the double quotations.

options="--version"

5. You can now execute the script! But you need to run it from the top
project source directory. So go there and simply run
'./tests/during-dev.sh'.

[... Truncated Text ...]




    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/task/?15813>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/