[build2] Feedback on the tutorial

[Klaim - Joël Lamotte]

I just finished the tutorial and playing with the basics of build2,
still a lot to do (build2 is quite complex! at least to understand well).

Anyway here are my notes, in case some improvements can be done on the
tutorial or
on build2 itself:

1. Sections should be numbered so that:
    - we can easily refer to them in discussions;
    - it is easy to resume when you paused somewhere in (it's a long
tutorial);
    - the different subjects we need to learn are clearly spottable;

2. It is not clear that the quickly-made manifest file should be in the
sources directory,
    not in the build directory in the configuration directory.
    I failed to understand that and lost a lot of time re-doing the
operations of this part
    until I tried with the manifest in the sources.
    It might be obvious, but when first reading it seemed the manifest was
only needed
    in the configuration directory because we were acting "like if" there
is a real package
    for the purpose of the tutorial. Not sure if everybody would have had
the same confusion.

3. When providing paths, it is not clear when or if a complete/cannonical
path is necessary or not.
    When I tried relative paths it seemed to work all the time, but from
the tutorial text it's
    not clear if it will cause problems later to do so.

4. The quotted syntax seem flexible, but in the same time quite complex for
cli.
    Not sure what to think yet about that.

5. When doing some of the cleaning commands, I get "permission denied"
(Windows 10) issues that I'm not
    sure where they come from. Usually it's because something is locking
the directory or one of it's file,
    but here when deleting by hand I have no problem so it's not that.


6. This line: "import libs = libhello%lib{hello}" from the buildfile
    is still obscure to me for now. I don't understand the part before the
% and why "hello" have to be
    named here.
    I didn't try yet to look into the rest of the doc, this feedback is
from reading the tutorial only
    (and sometime looking at help instructions).

7. I think it would be useful to have a last part at the end of the
tutorial that
    reminds things like this:
    > While some of this might not be crystal clear (like why do we have
bootstrap.build and root.build), I am sure you at least have a fuzzy idea
of what's going on. And that's enough for what we are after here.
Completely explaining what's going on here and, more importantly, why it's
going this way is for another time and place (the build2 build system
manual).

    That was in the middle already but a reminder at the end would be
useful.
    And a link to the build system manual would then be part of a nice
reading flow.

8. What I would like to know additionally in a tutorial like this:
  - how to share the part of the config files that are common to my
projects;
  - just a small example of installing hello and it's dependencies in a
separate directory;

9. I tried to add another project manually from memory, reached some errors
but so far the reports were clear enough (although a bit too compact to my
taste).
However I hit one error that is weird:

>>>>>>>>>>>>>>>>>>>>>
..\kikoo\kikoo.cpp:13:3: error: {}-imbalance detected
  info: while parsing ..\kikoo\mxx{kikoo}@kikoo-0.1.0\
  info: while applying rule cxx.compile to update kikoo-0.1.0\bmia{kikoo}
  info: while applying rule cxx.link to update kikoo-0.1.0\liba{kikoo}
  info: while applying rule bin.lib to update kikoo-0.1.0\lib{kikoo}
  info: while applying rule alias to update dir{kikoo-0.1.0\}
..\kikoo\kikoo.cpp:13:3: error: {}-imbalance detected
  info: while parsing ..\kikoo\mxx{kikoo}@kikoo-0.1.0\
  info: while applying rule cxx.compile to update kikoo-0.1.0\bmis{kikoo}
  info: while applying rule cxx.link to update kikoo-0.1.0\libs{kikoo}
  info: while applying rule bin.lib to update kikoo-0.1.0\lib{kikoo}
  info: while applying rule alias to update dir{kikoo-0.1.0\}
info: failed to update dir{kikoo-0.1.0\}
>>>>>>>>>>>>>>>>>>>>>>>


The first issue is that it appears twice but not all the time.
The second is that the error message is not clear. I now understand
that I forgot some ';' in module-specific lines of my file (not used to it
yet)
but I suspect the error to be from build2 and not from cl (which is the
compiler that I used).
If it is then it's their problem, but if it's not then this will be
problematic.
The compilers already have a hard time figuring out how to report errors in
a useful not-confusing
way, it would be good to use their reports instead of new ones.
Unfortunately I don't see
a good solution to this other than use parts of a compiler to do the
parsing.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.build2.org/archives/users/attachments/20171219/b1066564/attachment.html>