doc: document new feature from version 2.14

Added descriptions about new commandline options, STATIC
directive, symbol mingling, and some output format
specifics.

Signed-off-by: Chang S. Bae <chang.seok.bae@intel.com>
Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>

1 files changed, 139 insertions, 6 deletions

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 7b331d35..b6aab1c0 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -368,6 +368,8 @@ To get further usage instructions from NASM, try typing
 
 \c nasm -h
 
+\c{--help} option is also the same.
+
 As \c{-hf}, this will also list the available output file formats, and what they
 are.
 
@@ -657,10 +659,13 @@ option. So running
 is equivalent to running \c{nasm myfile.asm} and placing the
 directive \c{%include "myinc.inc"} at the start of the file.
 
+\c{--include} option is also accepted.
+
 For consistency with the \c{-I}, \c{-D} and \c{-U} options, this
 option can also be specified as \c{-P}.
 
 
+
 \S{opt-d} The \i\c{-d}\I\c{-D} Option: \I{pre-defining macros}Pre-Define a Macro
 
 \I\c{%define}Just as the \c{-p} option gives an alternative to placing
@@ -917,13 +922,72 @@ is indicated by an asterisk. For example:
 \c     dwarf     elf32 (i386) dwarf debug format for Linux
 
 
-\S{opt-pfix} The \i\c{--prefix} and \i\c{--postfix} Options.
+\S{opt-pfix} The \i\c{--(g|l)prefix}, \i\c{--(g|l)postfix} Options.
+
+The \c{--(g)prefix} options prepend the given argument
+to all \c{extern}, \c{common}, \c{static}, and \c{global} symbols, and the
+\c{--lprefix} option prepends to all other symbols. Similarly,
+\c{--(g)postfix} and \c{--lpostfix} options append
+the argument in the exactly same way as the \c{--xxprefix} options does.
+
+Running this:
+
+\c nasm -f macho --gprefix _
+
+is equivalent to place the directive with \c{%pragma macho gprefix _}
+at the start of the file (\k{mangling}). It will prepend the underscore
+to all global and external variables, as C requires it in some, but not all,
+system calling conventions.
+
+\S{opt-pragma} The \i\c{--pragma} Option
+
+NASM accepts an argument as \c{%pragma} option, which is like placing
+a \c{%pragma} preprocess statement at the beginning of the source.
+Running this:
+
+\c nasm -f macho --pragma "macho gprefix _"
+
+is equivalent to the example in \k{opt-pfix}.
+
+
+\S{opt-before} The \i\c{--before} Option
+
+A preprocess statement can be accepted with this option. The example
+shown in \k{opt-pragma} is the same as running this:
+
+\c nasm -f macho --before "%pragma macho gprefix _"
+
+
+\S{opt-limit} The \i\c{--limit-X} Option
+
+This option allows user to setup various maximum values for these:
+
+\b\c{--limit-passes}: Number of maximum allowed passes. Default is
+effectively unlimited.
+
+\b\c{--limit-stalled-passes}: Maximum number of allowed unfinished
+passes. Default is 1000.
+
+\b\c{--limit-macro-levels}: Define maximum depth of macro expansion
+(in preprocess). Default is 1000000.
+
+\b\c{--limit-rep}: Maximum number of allowed preprocessor loop, defined
+under \c{%rep}. Default is 1000000.
+
+\b\c{--limit-eval}: This number sets the boundary condition of allowed
+expression length. Default is 1000000.
+
+\b\c{--limit-lines}: Total number of source lines as allowed to be
+processed. Default is 2000000000.
+
+In example, running this limits the maximum line count to be 1000.
+
+\c nasm --limit-lines 1000
 
-The \c{--prefix} and \c{--postfix} options prepend or append
-(respectively) the given argument to all \c{global} or
-\c{extern} variables. E.g. \c{--prefix _} will prepend the
-underscore to all global and external variables, as C requires it in
-some, but not all, system calling conventions.
+
+\S{opt-keep-all} The \i\c{--keep-all} Option
+
+This option doesn't delete any output files even if an error happens.
 
 
 \S{nasmenv} The \i\c{NASMENV} \i{Environment} Variable
@@ -4607,6 +4671,62 @@ Once again, like \c{EXTERN} and \c{GLOBAL}, the primitive form of
 \c{COMMON} differs from the user-level form only in that it can take
 only one argument at a time.
 
+\H{static} \i\c{STATIC}: Local Symbols within Modules
+
+Opposite to \c{EXTERN} and \c{GLOBAL}, \c{STATIC} is local symbol,
+but should be named according to the global mangling rules (named
+by analogy with the C keyword "static" as applied to the functions).
+And like \c{GLOBAL} directive, the directive applying to a symbol
+should be \i{before} the definition of the symbol. For example:
+
+\c static foo
+\c foo:
+\c          ; codes
+
+Unlike \c{GLOBAL}, \c{STATIC} does not allow object formats to accept
+private extensions mentioned in \k{global}.
+
+\H{mangling} \i\c{(G|L)PREFIX}, \i\c{(G|L)POSTFIX}: Mangling Symbols
+
+\c{PREFIX}, \c{GPREFIX}, \c{LPREFIX}, \c{POSTFIX}, \c{GPOSTFIX}, and
+\c{LPOSTFIX} directives can prepend or append the given argument to
+a certain type of symbols. The directive should be as a preprocess
+statement. Each usage is:
+
+\b\c{PREFIX}|\c{GPREFIX}: Prepend the argument to all \c{EXTERN}
+\c{COMMON}, \c{STATIC}, and \c{GLOBAL} symbols
+
+\b\c{LPREFIX}: Prepend the argument to all other symbols
+such as Local Labels, and backend defined symbols
+
+\b\c{POSTFIX}|\c{GPOSTFIX}: Append the argument to all \c{EXTERN}
+\c{COMMON}, \c{STATIC}, and \c{GLOBAL} symbols
+
+\b\c{LPOSTFIX}: Append the argument to all other symbols
+such as Local Labels, and backend defined symbols
+
+This is a macro implemented as a \c{%pragma}:
+
+\c      %pragma macho lprefix L_
+
+Commandline option is also possible. See also \k{opt-pfix}.
+
+
+\H{gen-namespace} \i\c{OUTPUT}, \i\c{DEBUG}: Generic Namespaces
+
+\c{OUTPUT} and \c{DEBUG} are generic \c{%pragma} namespaces that are
+supposed to redirect to the current output and debug formats.
+For example, when mangling local symbols via the generic namespace:
+
+\c      %pragma output gprefix _
+
+This is useful when the directive is needed to be output format
+agnostic.
+
+The example is also euquivalent to this, when the output format is \c{elf}:
+
+\c      %pragma elf gprefix _
+
 
 \H{CPU} \i\c{CPU}: Defining CPU Dependencies
 
@@ -5731,6 +5851,19 @@ non-Mach-O builds of the same source code:
 
 \c      %pragma macho no_dead_strip symbol...
 
+\S{machosect} \c{macho} specific extensions to the \c{GLOBAL}
+Directive: \i\c{private_extern}
+
+The directive extension to \c{GLOBAL} marks the symbol with limited
+global scope. For example, you can specify the global symbol with
+this extension:
+
+\c global foo:private_extern
+\c foo:
+\c          ; codes
+
+Using with static linker will clear the private extern attribute.
+But linker option like \c{-keep_private_externs} can avoid it.
 
 \H{elffmt} \i\c{elf32}, \i\c{elf64}, \i\c{elfx32}: \I{ELF}\I{linux, elf}\i{Executable and Linkable
 Format} Object Files