README.1st

   1 This is a specially patched version of NASM.  It can be used to supplement
   2 building of Crystal Space, the Open Source 3D Engine project.  You can find
   3 Crystal Space at the following locations:
   4
   5 http://crystal.linuxgames.com/
   6 http://crystal.sourceforge.net/
   7
   8 Details of changes in this version of NASM follow.
   9
  10 -*- A new keyword %xdefine and its case-insensitive counterpart %ixdefine.
  11     They work almost the same way as %define and %idefine but expand
  12     the definition immediately, not on the invocation. Something like a cross
  13     between %define and %assign. The "x" suffix stands for "eXpand", so
  14     "xdefine" can be deciphered as "expand-and-define". Thus you can do
  15     things like this:
  16
  17         %assign ofs     0
  18
  19         %macro  arg     1
  20                 %xdefine %1 dword [esp+ofs]
  21                 %assign ofs ofs+4
  22         %endmacro
  23
  24 -*- Changed the place where the expansion of %$name macros are expanded.
  25     Now they are converted into ..@ctxnum.name form when detokenizing, so
  26     there are no quirks as before when using %$name arguments to macros,
  27     in macros etc. For example:
  28
  29         %macro  abc     1
  30                 %define %1 hello
  31         %endm
  32
  33         abc     %$here
  34         %$here
  35
  36     Now last line will be expanded to "hello" as expected. This also allows
  37     for lots of goodies, a good example are extended "proc" macros included
  38     in this archive.
  39
  40 -*- Added a check for "cstk" in smacro_defined() before calling get_ctx() -
  41     this allows for things like:
  42
  43         %ifdef %$abc
  44         %endif
  45
  46     to work without warnings even in no context.
  47
  48 -*- Added a check for "cstk" in %if*ctx and %elif*ctx directives -
  49     this allows to use %ifctx without excessive warnings. If there is
  50     no active context, %ifctx goes through "false" branch.
  51
  52 -*- Removed "user error: " prefix with %error directive: it just clobbers the
  53     output and has absolutely no functionality. Besides, this allows to write
  54     macros that does not differ from build-in functions in any way.
  55
  56 -*- Added expansion of string that is output by %error directive. Now you
  57     can do things like:
  58
  59         %define hello(x) Hello, x!
  60
  61         %define %$name andy
  62         %error "hello(%$name)"
  63
  64     Same happened with %include directive.
  65
  66 -*- Now all directives that expect an identifier will try to expand and
  67     concatenate everything without whitespaces in between before usage.
  68     For example, with "unfixed" nasm the commands
  69
  70         %define %$abc hello
  71         %define __%$abc goodbye
  72         __%$abc
  73
  74     would produce "incorrect" output: last line will expand to
  75
  76         hello goodbyehello
  77
  78     Not quite what you expected, eh? :-) The answer is that preprocessor
  79     treats the %define construct as if it would be
  80
  81         %define __ %$abc goodbye
  82
  83     (note the white space between __ and %$abc). After my "fix" it
  84     will "correctly" expand into
  85
  86         goodbye
  87
  88     as expected. Note that I use quotes around words "correct", "incorrect"
  89     etc because this is rather a feature not a bug; however current behaviour
  90     is more logical (and allows more advanced macro usage :-).
  91
  92     Same change was applied to:
  93         %push,%macro,%imacro,%define,%idefine,%xdefine,%ixdefine,
  94         %assign,%iassign,%undef
  95
  96 -*- A new directive [WARNING {+|-}warning-id] have been added. It works only
  97     if the assembly phase is enabled (i.e. it doesn't work with nasm -e).
  98
  99 -*- A new warning type: macro-selfref. By default this warning is disabled;
 100     when enabled NASM warns when a macro self-references itself; for example
 101     the following source:
 102
 103         [WARNING macro-selfref]
 104
 105         %macro          push    1-*
 106                 %rep    %0
 107                         push    %1
 108                         %rotate 1
 109                 %endrep
 110         %endmacro
 111
 112                         push    eax,ebx,ecx
 113
 114     will produce a warning, but if we remove the first line we won't see it
 115     anymore (which is The Right Thing To Do {tm} IMHO since C preprocessor
 116     eats such constructs without warnings at all).
 117
 118 -*- Added a "error" routine to preprocessor which always will set ERR_PASS1
 119     bit in severity_code. This removes annoying repeated errors on first
 120     and second passes from preprocessor.
 121
 122 -*- Added the %+ operator in single-line macros for concatenating two
 123     identifiers. Usage example:
 124
 125         %define _myfunc _otherfunc
 126         %define cextern(x) _ %+ x
 127         cextern (myfunc)
 128
 129     After first expansion, third line will become "_myfunc". After this
 130     expansion is performed again so it becomes "_otherunc".
 131
 132 -*- Now if preprocessor is in a non-emmitting state, no warning or error
 133     will be emmitted. Example:
 134
 135         %if 1
 136                 mov     eax,ebx
 137         %else
 138                 put anything you want between these two brackets,
 139                 even macro-parameter references %1 or local labels %$zz
 140                 or macro-local labels %%zz - no warning will be emmitted.
 141         %endif
 142
 143 -*- Context-local variables on expansion as a last resort are looked up
 144     in outer contexts. For example, the following piece:
 145
 146         %push   outer
 147         %define %$a [esp]
 148
 149                 %push   inner
 150                 %$a
 151                 %pop
 152         %pop
 153
 154     will expand correctly the fourth line to [esp]; if we'll define another
 155     %$a inside the "inner" context, it will take precedence over outer
 156     definition. However, this modification has been applied only to
 157     expand_smacro and not to smacro_define: as a consequence expansion
 158     looks in outer contexts, but %ifdef won't look in outer contexts.
 159
 160     This behaviour is needed because we don't want nested contexts to
 161     act on already defined local macros. Example:
 162
 163         %define %$arg1  [esp+4]
 164         test    eax,eax
 165         if      nz
 166                 mov     eax,%$arg1
 167         endif
 168
 169     In this example the "if" mmacro enters into the "if" context, so %$arg1
 170     is not valid anymore inside "if". Of course it could be worked around
 171     by using explicitely %$$arg1 but this is ugly IMHO.
 172
 173 -------------------------------// fixes for 0.98 //-----------------------------
 174
 175 -*- Fixed memory leak in %undef. The origline wasn't freed before
 176     exiting on success.
 177
 178 -----------------------------// Fixes for 0.98.01 //----------------------------
 179
 180 -*- Fixed trap in preprocessor when line expanded to empty set of tokens.
 181     This happens, for example, in the following case:
 182
 183         #define SOMETHING
 184         SOMETHING
 185
 186
 187 Andrew Zabolotny <bit@eltech.ru>