Re: [RFC PATCH 2/3] docs: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR

[Anthony PERARD <anthony.perard@xxxxxxxxxx>]

On Mon, Aug 21, 2023 at 06:54:38PM +0200, Nicola Vetrini wrote:
> diff --git a/docs/misra/Makefile b/docs/misra/Makefile
> new file mode 100644
> index 000000000000..f62cd936bfcc
> --- /dev/null
> +++ b/docs/misra/Makefile
> @@ -0,0 +1,36 @@
> +XEN_ROOT=$(CURDIR)/../..
> +include $(XEN_ROOT)/Config.mk
> +-include $(XEN_ROOT)/config/Docs.mk
> +
> +
> +TARGETS := $(addprefix C-runtime-failures,.c .o)
> +
> +all: $(TARGETS)
> +
> +define MISRA_HEADER
> +/*
> +
> +endef
> +
> +define MISRA_FOOTER
> +
> +*/
> +
> +endef
> +export MISRA_HEADER
> +export MISRA_FOOTER
> +
> +C-runtime-failures.c: C-runtime-failures.rst

Any reason not to use "%.c: %.rst" ? You could even write
    "C-runtime-failures.c: %.c: %.rst"
(Or even $(TARGETS:.o=.c): %.c %.rst", if TARGETS only had the .o, and
if we expect all *.c to be generated from *.rst in this Makefile)

> +# sed is used in place of cat to prevent occurrences of '*/'
> +# in the .rst from breaking the compilation

I think I'd like this comment just before the rule, rather than between
the target line and the recipe. That just push the recipe far way from
the target due to the indentation.

> +     ( \
> +       echo "$${MISRA_HEADER}"; \

Would it be ok to just do `echo "/*"` here instead of defining a make
variable and using it via the environment? I'd like to try to avoid the
dollar escape $$ which make shell code harder to read when written in
makefile.

> +       sed -e 's|*/|*//*|' $<; \

The first '*' in this command is awkward, as its a special character.
I'd rather not rely on `sed` to convert it to non-special, so could you
escape it?

Also, this pattern only takes care of the first occurrence of '*/' on a
line, but they could be more than one.

> +       echo "$${MISRA_FOOTER}" \
> +     ) > $@
> +
> +%.o: %.c
> +     $(CC) -c $< -o $@
> +
> +clean:
> +     rm -f *.c *.o

This `rm -f *.c` is prone to mistake. I hope no one is going to write a
C file in this directory, run `make clean` and lost their source. Or,
copy this makefile somewhere else. Would it be ok to just spell out all
the .c files that are expected to be generated by this makefile?

Cheers,

-- 
Anthony PERARD