Math tutorial

[bocchino]

Originating Project/Creator	F Prime
Affected Component	Math tutorial
Affected Architectures(s)	Ref
Related Issue(s)	N/A
Has Unit Tests (y/n)	y
Builds Without Errors (y/n)	y
Unit Tests Pass (y/n)	y
Documentation Included (y/n)	y

---

Change Description

This PR updates the tutorial at docs/MathComponent to use FPP instead of XML as the source language. It also makes two incidental changes that are necessary for the tutorial to work as described:

1. Revise the component implementation template autocoder to use the name Component instead of Component ComponentImpl. This change conforms to the latest F Prime conventions.
2. Restore console logging in the Ref application by implementing a subclass of Fw::Logger that prints to the console. It appears that Ref console logging was dropped at some point. I think it is useful for the Ref app to show how to use the logger interface.

Rationale

This PR includes essential documentation for release 3.0.

Testing/Review Recommendations

I made some changes to the content of the tutorial. Specifically, I simplified and revised the use of types, I simplified the command interface, and I refactored the unit tests to remove code duplication between tests. I also removed image files and sequence files that were out of date and that were not mentioned in the tutorial. You may want to review these changes.

I recommend that we go with this version, which I believe suffices for release 3.0. If we want to add more complexity, we can add another tutorial or we can update this tutorial later. I believe the current tutorial covers all the essential features of FPP modeling, building, and testing.

I have delivered the revised tutorial in AsciiDoc. I believe it is a much better choice than Markdown for moderately complex documentation like this. We have an agenda item to discuss the merits of using AsciiDoc vs. sticking with Markdown.

Future Work

• Once we have fpp-check -u integrated with the build system, update this tutorial to explain how to use it.
• Update the other tutorials.

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• fpv
• mul
• nodemon
• toc
• toclevels

Previously acknowledged words that are now absent

acwrap bc bootup cmak concat Connectedoutput dfdc differend eb EXTN FH Fixme followd inttype lgcov libasan libsan llx Netscape's nosetests OMG's OParg PASSIVEC pipsetup PTLM PYTHON serialns setname setopt setresult setval SQL's stdarg strcat strcpy templating tgz wget workaround

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the git@github.com:bocchino/fprime.git repository
on the math-tutorial branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/nasa/fprime/issues/comments/967609891" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• adoc
• asciidoctor
• fpv
• mul
• nodemon
• toc
• toclevels
• vn

Previously acknowledged words that are now absent

acwrap bc bootup cmak concat Connectedoutput dfdc differend eb EXTN FH Fixme followd inttype lgcov libasan libsan llx Netscape's nosetests OMG's OParg PASSIVEC pipsetup PTLM PYTHON serialns setname setopt setresult setval SQL's stdarg strcat strcpy templating tgz wget workaround

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the git@github.com:bocchino/fprime.git repository
on the math-tutorial branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/nasa/fprime/issues/comments/967611292" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• fh
• fixme

Previously acknowledged words that are now absent

bc bootup concat Connectedoutput dfdc inttype Netscape's OMG's strcat strcpy templating tgz wget workaround

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the git@github.com:bocchino/fprime.git repository
on the math-tutorial branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/nasa/fprime/issues/comments/967698995" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• Inttype

Previously acknowledged words that are now absent

bc bootup concat Netscape's OMG's strcat strcpy templating tgz wget workaround

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the git@github.com:bocchino/fprime.git repository
on the math-tutorial branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/nasa/fprime/issues/comments/967701376" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

[LeStarch]

I see a lot of utility scripts and some JSON checked in. Is this needed?

What are the ramifications of changing the component autocoded name in the template files? Is this going to break fprime-util new or other tooling?

[bocchino]

I see a lot of utility scripts and some JSON checked in. Is this needed?

The utility scripts in adoc/ are to avoid hand-copying the reference application into the AsciiDoc document. For maintainability, I recommend that we leave them in.

In json/, json.txt is the F Prime Layout form of the example diagram. I recommend keeping it for reference. We could delete it because it is auto-generated from top.txt.

[bocchino]

What are the ramifications of changing the component autocoded name in the template files? Is this going to break fprime-util new or other tooling?

I did a quick test. fprime-util new doesn't seem to care about the class name in the implementation. It does assume that the implementation file is named FooComponent.{hpp,cpp} or FooComponentImpl.{hpp,cpp). So to use release 3.0 naming convention (also expected by FPP), you need to do a bit of renaming after invoking fprime-util new. This seems like an fprime-util new issue, not a math tutorial issue.

I'm not aware of any other tool that will break. Also, if some tool does break, we should fix the tool, since this naming scheme is the release 3.0 convention.

[LeStarch]

@bocchino it is an fprime-util new issue. Just wanted to confirm that fprime-util new did not crash or something. We do need to rework it to put in FPP files and better naming conventions.