[binutils-gdb] Add documentation to gdb_compile

[Simon Marchi <simark at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=aff9c0f8ab32e4f2f7ff9700afe84a61d23a08c6

commit aff9c0f8ab32e4f2f7ff9700afe84a61d23a08c6
Author: Simon Marchi <simon.marchi@ericsson.com>
Date:   Fri Dec 18 13:39:26 2015 -0500

    Add documentation to gdb_compile
    
    This patch adds some documentation to gdb_compile.  It describes the
    various options that can influence compilation.  Most of them are
    handled by DejaGnu, but are not really documented anywhere, so I think
    it's good to have a quick reference.  Not all possible options are
    described, that would add way to much noise.  I chose those that I think
    are relevant in the context of writing a test case.
    
    gdb/testsuite/ChangeLog:
    
    	* lib/gdb.exp (gdb_compile): Add function doc.

Diff:
---
 gdb/testsuite/ChangeLog   |  4 ++++
 gdb/testsuite/lib/gdb.exp | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/gdb/testsuite/ChangeLog b/gdb/testsuite/ChangeLog
index 43c22b1..3dd3104 100644
--- a/gdb/testsuite/ChangeLog
+++ b/gdb/testsuite/ChangeLog
@@ -1,3 +1,7 @@
+2015-12-18  Simon Marchi  <simon.marchi@ericsson.com>
+
+	* lib/gdb.exp (gdb_compile): Add function doc.
+
 2015-12-17  Pedro Alves  <palves@redhat.com>
 
 	PR threads/19354
diff --git a/gdb/testsuite/lib/gdb.exp b/gdb/testsuite/lib/gdb.exp
index beb97ea..333b988 100644
--- a/gdb/testsuite/lib/gdb.exp
+++ b/gdb/testsuite/lib/gdb.exp
@@ -3297,6 +3297,40 @@ proc gdb_wrapper_init { args } {
 global gdb_saved_set_unbuffered_mode_obj
 set gdb_saved_set_unbuffered_mode_obj ""
 
+# Compile source files specified by SOURCE into a binary of type TYPE at path
+# DEST.  gdb_compile is implemented using DejaGnu's target_compile, so the type
+# parameter and most options are passed directly to it.
+#
+# The type can be one of the following:
+#
+#   - object: Compile into an object file.
+#   - executable: Compile and link into an executable.
+#   - preprocess: Preprocess the source files.
+#   - assembly: Generate assembly listing.
+#
+# The following options are understood and processed by gdb_compile:
+#
+#   - shlib=so_path: Add SO_PATH to the sources, and enable some target-specific
+#     quirks to be able to use shared libraries.
+#   - shlib_load: Link with appropriate libraries to allow the test to
+#     dynamically load libraries at runtime.  For example, on Linux, this adds
+#     -ldl so that the test can use dlopen.
+#   - nowarnings:  Inhibit all compiler warnings.
+#
+# And here are some of the not too obscure options understood by DejaGnu that
+# influence the compilation:
+#
+#   - additional_flags=flag: Add FLAG to the compiler flags.
+#   - libs=library: Add LIBRARY to the libraries passed to the linker.  The
+#     argument can be a file, in which case it's added to the sources, or a
+#     linker flag.
+#   - ldflags=flag: Add FLAG to the linker flags.
+#   - incdir=path: Add PATH to the searched include directories.
+#   - libdir=path: Add PATH to the linker searched directories.
+#   - ada, c++, f77: Compile the file as Ada, C++ or Fortran.
+#   - debug: Build with debug information.
+#   - optimize: Build with optimization.
+
 proc gdb_compile {source dest type options} {
     global GDB_TESTCASE_OPTIONS
     global gdb_wrapper_file