diff options
Diffstat (limited to 'doc/references/CommandReference.rst')
| -rw-r--r-- | doc/references/CommandReference.rst | 15 |
1 files changed, 14 insertions, 1 deletions
diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index de6ff5415..2b53e51f3 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -116,6 +116,8 @@ Lines [``--lines``] Display on the standard output lines of files preceded by line number. +.. _gccllvm-only-programs: + GCC/LLVM only commands ====================== @@ -128,6 +130,9 @@ Bind [``--bind``] Performs only the first stage of the elaboration command; the list of object files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. +.. HINT:: + Currently, the objects generated by ``--bind`` are created in the working directory. This behaviour is different from other object files generated with ``-a``, which are always placed in the same directory as the `WORK` library. It is possible to provide an output path with ``ghdl --bind -o path/primary_unit primary_unit``. However, ``ghdl --list-link`` will only search in the current path. + .. index:: cmd GCC/LLVM linking Link [``--link``] @@ -144,7 +149,13 @@ List link [``--list-link``] .. option:: --list-link <primary_unit [secondary_unit]> -This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable. This command is intended to add object files in a link of a foreign program. +This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable and additional arguments for the linker. This command is intended to add object files in a link of a foreign program. This command should be used only after ``ghdl --bind``, as some files generated by it are looked for in the current path. + +.. HINT:: + One of the arguments returned by ``--list-link`` is ``-Wl,--version-script=PREFIX/lib/ghdl/grt.ver``, where `PREFIX` is the installation path of GHDL. This will hide most of the symbols when the target executable binary is built. In some contexts, where the binary is to be loaded dynamically, the user might want additional symbols to be accessible. There are two possible approaches to have it done: + + * Filter the output of ``--list-link`` with e.g. ``sed``. + * Provide an additional non-anonymous version script: ``-Wl,-Wl,--version-script=file.ver``. Options ======= @@ -175,6 +186,8 @@ Use ``COMMAND`` as the command name for the assembler. If ``COMMAND`` is not a p Use ``COMMAND`` as the linker driver. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``gcc``. +.. _passing-options-to-other-programs: + Passing options to other programs ================================= |