Contents of /MITgcm_contrib/mlosch/tools/README

This version of genmake2 handles the new type of output of TAF v2,
i.e. the fact that the forward code that TAF thinks relevant is
returned together with the derivative code, in a different way than
the original genmake2: Instead of concatenating all fortran sources
and sending one monolithic ad_input_code.f to TAF, the sources are
sent to TAF directly: staf [options] $(FLOWFILES) $(AD_FILES). This
makes it faster to compile the returned sources because you can use
the "parallel" capabilities of (g)make (with option -j n); also you
can modify individual sources (that have been returned by TAF) without
having to recompile a large ad_taf_output.f making debugging a little
easier.

This version of genmake2 works with both testreport -adm and testreport -tlm. 

genmake2_patch.diff patches the "official" genmake2 until hopefully
this version makes into the main repository.  Usage:
patch -p1 your_genmake2 genmake2_patch.diff

In order to make this work I had to modify the target ad_taf_output.f
(and similarly ftl_taf_output.f) and introduce new targets:

- remove_comments applies \$(TOOLSDIR)/remove_comments_sed to all
$(AD_FILES) will remove the comments, this may be annoying, if you are
used to working with the *.f files and need to comments for
orientation within the file, but I think that the *.f files can be
generated so easily, that this does not matter much. This target is
really only needed if you have a slow uplink and want to sent smaller
files to staf

- adj_sed and ftl_sed apply $(TOOLSDIR)/adjoint_sed to
  $(AD_FILES:.$FS=_ad/tl.$FS) 

- adjobjfiles and ftlobjfiles force compiling the taf-generated files
  after the $(TAF) command

The TAMC related target are not touched, but I did not test the result

Issues:
>>>> The Makefile still generates ad_taf_output.f and ftl_taf_output.f to
be used for svd_taf (although I am not sure, if this will work,
because I don't know how it is supposed to work). <<<<

>>>> The targets adonlyfwd, adtrick will probably not work, but do we
still need them? <<<<

>>>> The $(EXE_AD/FTL) targets now depends on ad/ftl_taf_output.$FS
(not .o anymore), which is generated after making adjobjfiles. This is
a bit of a hack and potentially fragile, but I couldn't think of
anything else to trick "make" into compiling in two separate
steps. <<<<

>>>> Another weakness is the "inplace" use of sed, (sed -i), which
will not work with some sed implementations (POSIX?). Alternatively
one could modify the .F.$FS and .$FS.o rules like this:

.F.$FS:
        sed -f \$(TOOLSDIR)/remove_comments_sed \$< > \$<.tmp && mv \$<.tmp \$<
        \$(CPPCMD) > \$@
.$FS.o:
        sed -f \$(TOOLSDIR)/adjoint_sed \$< > \$<.tmp && mv \$<.tmp \$<
        $(FC) $(FFLAGS) $(FOPTIM) -c $<

but these would then be applied to all files and not only
the $(AD_FILES). Any suggestion how to improve this is very welcome. <<<<
1	This version of genmake2 handles the new type of output of TAF v2,
2	i.e. the fact that the forward code that TAF thinks relevant is
3	returned together with the derivative code, in a different way than
4	the original genmake2: Instead of concatenating all fortran sources
5	and sending one monolithic ad_input_code.f to TAF, the sources are
6	sent to TAF directly: staf [options] $(FLOWFILES) $(AD_FILES). This
7	makes it faster to compile the returned sources because you can use
8	the "parallel" capabilities of (g)make (with option -j n); also you
9	can modify individual sources (that have been returned by TAF) without
10	having to recompile a large ad_taf_output.f making debugging a little
11	easier.
12
13	This version of genmake2 works with both testreport -adm and testreport -tlm.
14
15	genmake2_patch.diff patches the "official" genmake2 until hopefully
16	this version makes into the main repository. Usage:
17	patch -p1 your_genmake2 genmake2_patch.diff
18
19	In order to make this work I had to modify the target ad_taf_output.f
20	(and similarly ftl_taf_output.f) and introduce new targets:
21
22	- remove_comments applies \$(TOOLSDIR)/remove_comments_sed to all
23	$(AD_FILES) will remove the comments, this may be annoying, if you are
24	used to working with the *.f files and need to comments for
25	orientation within the file, but I think that the *.f files can be
26	generated so easily, that this does not matter much. This target is
27	really only needed if you have a slow uplink and want to sent smaller
28	files to staf
29
30	- adj_sed and ftl_sed apply $(TOOLSDIR)/adjoint_sed to
31	$(AD_FILES:.$FS=_ad/tl.$FS)
32
33	- adjobjfiles and ftlobjfiles force compiling the taf-generated files
34	after the $(TAF) command
35
36	The TAMC related target are not touched, but I did not test the result
37
38	Issues:
39	>>>> The Makefile still generates ad_taf_output.f and ftl_taf_output.f to
40	be used for svd_taf (although I am not sure, if this will work,
41	because I don't know how it is supposed to work). <<<<
42
43	>>>> The targets adonlyfwd, adtrick will probably not work, but do we
44	still need them? <<<<
45
46	>>>> The $(EXE_AD/FTL) targets now depends on ad/ftl_taf_output.$FS
47	(not .o anymore), which is generated after making adjobjfiles. This is
48	a bit of a hack and potentially fragile, but I couldn't think of
49	anything else to trick "make" into compiling in two separate
50	steps. <<<<
51
52	>>>> Another weakness is the "inplace" use of sed, (sed -i), which
53	will not work with some sed implementations (POSIX?). Alternatively
54	one could modify the .F.$FS and .$FS.o rules like this:
55
56	.F.$FS:
57	sed -f \$(TOOLSDIR)/remove_comments_sed \$< > \$<.tmp && mv \$<.tmp \$<
58	\$(CPPCMD) > \$@
59	.$FS.o:
60	sed -f \$(TOOLSDIR)/adjoint_sed \$< > \$<.tmp && mv \$<.tmp \$<
61	$(FC) $(FFLAGS) $(FOPTIM) -c $<
62
63	but these would then be applied to all files and not only
64	the $(AD_FILES). Any suggestion how to improve this is very welcome. <<<<