Create user manual.

The test structure of the tests along with an unique sample folder are badly organised.
There should be a sample source containing multiple projects each one testing (and thus showing a sample) of a particular feature.
The directory structure should look something like this:

• tests
  • feature1
    • test project for feature 1
  • feature2
    • test project for feature 2
• mk

Investigate a way to define and access local variables that is more intuitive than the current getters and setters.

The new way should be:
i) more intuitive, that is more similar to the normal way to define variables

myvar := myvalue

ii) shorter, it should not clog the screen with function calls: to make local variables really useful it shouldn't take a whole

$(call anrem-local-get, my_local_name)

to get the value.

Consider adding some kind of helper for multiline commands in rules

Currently scope.mk files do not have access to the current path, this is a problem since the current path is useful to define ignore paths relative to the scope file.

Add information targets that display informations about the current anrem project.
Some example command targets are:

• list namespaces
• list modules
• list targets
• show specific variable value
• debug variables content

Handle inclusions in a better way:
includes should show better to which module the included file belongs, such as

#include my_module_name/my_header.h

Inherithed includes should be handled automatically, this means that if module A is including b.h from module B, and b.h is including c.h from module C, both module C and module B paths (or at least the place where the included files are) must be reachable by the compiler (such as with gcc -I my/path/to/includes).

// a.c
#include B/b.h
// -- end of a.c

// b.h
#include C/c.h
// -- end of b.h 

This should cause an output with the following meaning:

gcc -o my_executable -I path/to/B/parent -I path/to/C/parent a.c 

Moreover the number of directories given as -I should be minimal to avoid clashes with namings that were not intended by the developer.

A possible solution would be to keep a separate directory (say mk/link_dir) where links to every module are kept, then the only thing needed by the compiler is:

gcc -o my_executable -I mk/link_dir a.c

with

ls -l mk/link_dir
lrwxr-xr-x A -> path/to/module/A
lrwxr-xr-x B -> path/to/module/B
lrwxr-xr-x C -> path/to/module/C

Advantages of the solution:

1. Keeps the format of the include directives as preferred
2. Fairly easy to implement
3. Can switch seamlessly from the modular workflow to the classic one (the one with a single include dir with all the headers in it)
4. May implicitly solve some problems of cross module inclusion and target group dependency handling

Disadvantages:

1. Need some link check/creation code to be run at every make call
2. Need also to investigate possible problems with module name clashes.

Sometimes cli tools require absolute paths (e.g. VBoxManage while creating a new vm and specifying the base folder path).

Is it possible to have an 'anrem-current-path' like function to get the absolute path inside a module?

Hint: an absolute path could be easily obtained using

readlink -f (dir relative to the working directory).

See issue #3.
In this case we want to have a single (or a few) global include directories, containing all the elements that have to be included.
This opens the possibility to use the same include path for both the modular and classic workflows; the difference is where the included files are actually stored.
In the classical workflow there is a root include directory containing all the included files (say header files) which can also be coincident with the root directory of the modules.
Case 1: separate include dir

├─  src
│     ├─ module_A
│     │     ├─ a.c
│     ├─ module_B
│     │     ├─ b.c
├─  include
│     ├─ module_A
│     │     ├─ a.h
│     ├─ module_B
│     │     ├─ b.h

Then the gcc call will look like:

gcc -I include a.c b.c

Case 2: include dir = source dir

├─  src
│     ├─ module_A
│     │     ├─ a.c
│     │     ├─ a.h
│     ├─ module_B
│     │     ├─ b.c
│     │     ├─ b.h

In this second case full paths could be used to identify a file to be included (as usual) but the possibility to rearrange the module tree is lost; the gcc call would be something like

gcc -I src a.c b.c

Along with ticket #5 it is needed to be able to scope variables in the project to achieve full isolation, especially for compiler flags and things like that.

Local variables containing lists, when expanded as $(@var_name) are truncated to the first element.

Description

Per-subtree local variables are variables that are defined as "local" in a module and are visible by all submodules.
In practice we have:

proj/module_a
proj/module_a/module_b

With the following module_a/module.mk

# set subtree local variable "localvar" to "foo"
$(call anrem-set-subtree-local, localvar, foo)`

and module_b/module.mk

# get subtree local variable "localvar" value (which should be foo)
$(call anrem-get-subtree-local, localvar)
# yields foo

Note the difference with "normal" local symbols as the get operation in module_b would have returned NULL.

Use case

This feature seems to be useful when having submodules that must be compiled with different flags or require a different value of a common variable that can be set in the top-level module for convenience.
Follows an example with two libraries.

# lib/module.mk
CURR := $(call anrem-current-path)
$(call anrem-set-subtree-local, CFLAGS, -I$(CURR)/include)

# lib/libfoo/module.mk
foo.o: foo.c
    gcc $(call anrem-get-subtree-local, CFLAGS) -o $@ $<

Every time I use ANREM for a project and the time comes for me to write the build module mk, it's always a nightmare.
Imagine you have 10 modules containing 5 objects each and you need all these objects linked together to let your wonderful project see the light of life.
Normally I would write standard make stuff like:
SOURCES := $(wildcard *.c)
OBJS := $(patsubst %.c,%.o,$(SOURCES))
and then
build_target : $(OBJS)
$CC -o $@ $< bla bla bla.
But now, since I started to use ANREM, obtaining very well-designed project tree, I'm getting stuck in the mud with this:
$(call anrem-build, $(BUILD_TARGET)) : $(MOD_one)/obj1.o $(MOD_one)/obj2.o [...] $(MOD_i)/objk.o [...] $(MOD_ten)/obj4.o $(MOD_ten)/obj5.o.
and FINALLY
$CC -o $@ $< bla bla bla.
This is a not good feature sir!!! 👎

Wouldn't it be great if each of those ten modules could simply ask ANREM to add himself to the build target linking list? (I suggest the name: anrem-add-me-to-the-build).

Previously the order of parsing of the directory tree of the modules was not important.

With the addition of new features, namely the possibility to ignore paths and the fully qualified module variable names (such as ||[|...]), it is required that the paths are evaluated in breadth first order.

This has been discovered while working for issue #2, in practice it has been found that it can be useful to have a subproject automatically included and compiled by simply putting it in a directory inside the project.

The goal is to provide a way to easily add third party projects inside the tree (much like git submodule) and compile them without the need of touching their structure or makefiles; all this keeping the non-recursive make strategy.