aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJacob Bachmeyer <jcb62281+dev@gmail.com>2020-05-26 10:00:36 -0600
committerRob Savoye <rob@senecass.com>2020-05-26 10:05:35 -0600
commit738c8c07c5e1b0ae23d2d722acc95c334aa254d8 (patch)
treee9eca49d47b89771f81e83793ed568639c4d3058
parent16a6991256c245eafafa3ebe7ff9e4498ec3645f (diff)
downloaddejagnu-738c8c07c5e1b0ae23d2d722acc95c334aa254d8.zip
dejagnu-738c8c07c5e1b0ae23d2d722acc95c334aa254d8.tar.gz
dejagnu-738c8c07c5e1b0ae23d2d722acc95c334aa254d8.tar.bz2
Add documentation for target_compile procedure.
-rw-r--r--ChangeLog11
-rw-r--r--doc/dejagnu.texi208
2 files changed, 197 insertions, 22 deletions
diff --git a/ChangeLog b/ChangeLog
index 40d4386..2dd6cad 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2020-05-26 Jacob Bachmeyer <jcb62281+dev@gmail.com>
+
+ * doc/dejagnu.texi (target_compile procedure): Add documentation.
+
+2020-05-26 Jacob Bachmeyer <jcb62281+dev@gmail.com>
+
+ * doc/dejagnu.texi (target_link procedure): New stub node.
+ (default_link procedure): Document internal procedure.
+ (default_target_assemble procedure): Likewise.
+ (default_target_compile procedure): Likewise.
+
2020-05-20 Jacob Bachmeyer <jcb62281+dev@gmail.com>
* baseboards/{aarch64-sim, arm-ice, arm-sim, basic-sid, iq2000-sim,
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
index 34b11a1..bb386e8 100644
--- a/doc/dejagnu.texi
+++ b/doc/dejagnu.texi
@@ -4408,6 +4408,7 @@ This is the filename to download.
* reboot_target Procedure: reboot_target procedure
* target_assemble Procedure: target_assemble procedure
* target_compile Procedure: target_compile procedure
+* target_link Procedure: target_link procedure
@end menu
@node default_link procedure, default_target_assemble procedure, , Procedures For Target Boards
@@ -4418,12 +4419,8 @@ This is the filename to download.
@t{@b{default_link} @i{board} @i{objects} @i{destfile} @i{flags}}
@end quotation
-@table @asis
-@item @code{board}
-@item @code{objects}
-@item @code{destfile}
-@item @code{flags}
-@end table
+This is the internal implementation for the @ref{target_link
+procedure}, and should not be directly called from testsuite code.
@node default_target_assemble procedure, default_target_compile procedure, default_link procedure, Procedures For Target Boards
@subsubheading default_target_assemble Procedure
@@ -4433,11 +4430,8 @@ This is the filename to download.
@t{@b{default_target_assemble} @i{source} @i{destfile} @i{flags}}
@end quotation
-@table @asis
-@item @code{source}
-@item @code{destfile}
-@item @code{flags}
-@end table
+This is the internal implementation for the @ref{target_assemble
+procedure}, and should not be directly called from testsuite code.
@node default_target_compile procedure, pop_config procedure, default_target_assemble procedure, Procedures For Target Boards
@subsubheading default_target_compile Procedure
@@ -4448,12 +4442,11 @@ This is the filename to download.
@i{options}}
@end quotation
-@table @asis
-@item @code{source}
-@item @code{destfile}
-@item @code{type}
-@item @code{options}
-@end table
+This is the default implementation for the @ref{target_compile
+procedure}, and is used if the current target board does not have a
+special procedure for this purpose. @xref{target_compile procedure},
+for API details. Calling this procedure directly from testsuite code
+is deprecated.
@node pop_config procedure, prune_warnings procedure, default_target_compile procedure, Procedures For Target Boards
@subsubheading pop_config Procedure
@@ -4529,7 +4522,7 @@ Reboot the target.
@item @code{flags}
@end table
-@node target_compile procedure, , target_assemble procedure, Procedures For Target Boards
+@node target_compile procedure, target_link procedure, target_assemble procedure, Procedures For Target Boards
@subsubheading target_compile Procedure
@findex target_compile
@@ -4537,11 +4530,182 @@ Reboot the target.
@t{@b{target_compile} @i{source} @i{destfile} @i{type} @i{options}}
@end quotation
+@table @code
+@item source
+Source file or other arguments if @var{type} is @code{none}.
+@item destfile
+Destination file or empty string to request output as return value.
+@item type
+Type of output that should be produced.
+@multitable {@code{preprocess}} {Special applications where no source is actually given.}
+@item @code{none}
+@tab Special applications where no source is actually given.
+@item @code{preprocess}
+@tab Run the source files through the C preprocessor.
+@item @code{assembly}
+@tab Produce assembler source from the compiler.
+@item @code{object}
+@tab Produce binary object files.
+@item @code{executable}
+@tab Produce an executable program.
+@end multitable
+@item options
+List of additional options:
+
+@b{Language-selection options:}
+@table @code
+@item ada
+Use an Ada compiler.
+@item c++
+Use a C++ compiler.
+@item d
+Use a compiler for the D language.
+@item f77
+Use a compiler for Fortran 77.
+@item f90
+Use a compiler for Fortran 90.
+@end table
+If none of these options are given, the C compiler is used by default.
+Giving multiple language-selection options is an error.
+
+The @code{f77} option generally selects the @command{g77} compiler,
+while the @code{f90} option selects the newer @command{gfortran}
+frontend. Both of these can compile Fortran 77, but only
+@command{gfortran} supports Fortran 90.
+
+@b{Search path options:}
+@table @code
+@item incdir=@var{dir}
+Additional directory to search for preprocessor include files.
+Multiple uses of this option add multiple directories to the search
+path.
+@item libdir=@var{dir}
+Additional directory to search for libraries. Multiple uses of this
+option add multiple directories to the search path.
+@end table
+
+@b{Target options:}
+@table @code
+@item debug
+Compile with debugging information. Multiple uses of this option are
+treated as a single use.
+@item dest=@var{target}
+Override the current target and compile for @var{target} instead. If
+this option is given multiple times, only the last use is significant.
+@item compiler=@var{command}
+Override the defaults and use @var{command} as the compiler. If
+this option is given multiple times, only the last use is significant.
+@item additional_flags=@var{flags}
+Add @var{flags} to the set of arguments to be passed to the compiler.
+Multiple uses of this option specify additional arguments.
+@item optimize=@var{flags}
+Specify optimization flags to be passed to the compiler. Nothing
+enforces that the flags given with option must actually be related to
+optimization, however. If this option is given multiple times, only
+the last use is significant.
+@item ldflags=@var{flags}
+Add @var{flags} to the set of arguments to be passed to the linker.
+Note that these are passed literally to the compiler driver, without
+adding a special prefix to each option. If a @samp{-Wl,} prefix is
+needed with GCC, it must be included in the given @var{flags}. As a
+group, the linker flags are only used if an executable is requested
+and are given special treatment with some languages. Multiple uses of
+this option specify additional arguments.
+@item ldscript=@var{script}
+Specify a linker script, or more precisely, the argument to pass to
+the linker via the compiler driver to select a linker script. The
+@var{script} value is passed literally to the compiler driver. If
+this option is given multiple times, only the last use is significant.
+@item libs=@var{libs}
+Specify additional libraries to be included in the link. The
+@var{libs} value is a space-separated list of libraries to include.
+Each element is checked, and if a file exists with that exact name, it
+is added to the list of sources to be given to the compiler.
+Otherwise, the element is passed literally to the compiler driver
+after any linker flags specified with the @code{ldflags} option.
+Multiple uses of this option specify additional lists, which are
+concatenated in the order they are given.
+@end table
+
+@b{Execution options:}
+@table @code
+@item timeout=@var{timeout}
+Abort the compile job if it is still running after @var{timeout}
+seconds. This is intended for compiler tests that are known to cause
+infinite loops upon failure.
+@item redirect=@var{file}
+Instead of returning output emitted on @code{stdout}, place it into
+@var{file}.
+@end table
+@end table
+
+The @code{target_compile} procedure also uses several global Tcl variables as overrides:
+@table @code
+@item CFLAGS_FOR_TARGET
+If @code{CFLAGS_FOR_TARGET} is set, its value is prepended to the
+flags otherwise prepared for the compiler, even ahead of any
+board-specific flags inserted as a result of a language-selection
+option.
+@item LDFLAGS_FOR_TARGET
+If @code{LDFLAGS_FOR_TARGET} is set, the set of arguments to be passed
+to linker is initialized to its value instead of an empty list. The
+@code{ldflags} option appends to this list.
+@item CC_FOR_TARGET
+Override default compiler. If no other compiler is given and this
+variable is set, its value will be used instead of searching for a
+compiler or using the default from the target board configuration.
+The @code{compiler} option overrides this variable.
+@item CXX_FOR_TARGET
+Override C++ compiler. If the @code{c++} option is given, this
+compiler will be used and the @code{compiler} option ignored.
+@item D_FOR_TARGET
+Override D language compiler. If the @code{d} option is given, this
+compiler will be used and the @code{compiler} option ignored.
+@item F77_FOR_TARGET
+Override Fortran 77 compiler. If the @code{f77} option is given, this
+compiler will be used and the @code{compiler} option ignored.
+@item F90_FOR_TARGET
+Override Fortran 90 compiler. If the @code{f90} option is given, this
+compiler will be used and the @code{compiler} option ignored.
+@item GNATMAKE_FOR_TARGET
+Override Ada compiler. If the @code{ada} option is given, this
+compiler will be used and the @code{compiler} option ignored.
+@end table
+
+The @code{target_compile} procedure obtains most defaults from the
+target board configuration, but additionally inserts any flags
+specified as @code{cflags_for_target} on the @emph{host} board
+configuration. If no host is set, the @code{unix} board configuration
+is checked for a @code{cflags_for_target} key. If the
+@code{cflags_for_target} key exists, its value is inserted into the
+set of arguments given to the compiler after any arguments given with
+the @code{additional_flags} option.
+
+In DejaGnu 1.6.2 and older, this mechanism did not work reliably and
+the @code{unix} board configuration was always searched for the
+@code{cflags_for_target} key, regardless of the host board selected.
+
+Also in DejaGnu 1.6.2 and older, the @code{dest} option interacted
+very badly with the language-selection options. There was no correct
+way to combine these options because the language-specific defaults
+would be read from the current target board configuration instead of
+the board configuration specified with the @code{dest} option. The
+closest solution was to always specify the language-selection option
+first, but this results in defaults appropriate for the current
+target, instead of the target selected with the @code{dest} option.
+
+@node target_link procedure, , target_compile procedure, Procedures For Target Boards
+@subsubheading target_link Procedure
+@findex target_link
+
+@quotation
+@t{@b{target_link} @i{objects} @i{destfile} @i{flags}}
+@end quotation
+
@table @asis
-@item @code{source}
+@item @code{objects}
@item @code{destfile}
-@item @code{type}
-@item @code{options}
+@item @code{flags}
@end table
@node target database library file, platform dependent procedures, Procedures For Target Boards, Built-in Procedures
@@ -5675,4 +5839,4 @@ This makes @code{runtest} exit. Abbreviation: @kbd{q}.
@c LocalWords: subdirectory prepend prepended testsuite filename Expect's svn
@c LocalWords: DejaGnu CVS RCS SCCS prepending subcommands Tcl Awk Readline
-@c LocalWords: POSIX KFAIL KPASS XFAIL XPASS hostname
+@c LocalWords: POSIX KFAIL KPASS XFAIL XPASS hostname multitable gfortran