Mercurial > hg-old > index.cgi

comparison doc/manual.docbook.sgml @ 396:62cb50c50976

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cosmetic updates to documentation; added warning pseudo op
author lost@l-w.ca
date Fri, 23 Jul 2010 17:08:57 -0600
parents ed3553296580
children 0324fd09c7ac
comparison
equal deleted inserted replaced
395:54499b799779 396:62cb50c50976
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"> 1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
2 <book> 2 <book>
3 <bookinfo> 3 <bookinfo>
4 <title>LW Tool Chain</title> 4 <title>LW Tool Chain</title>
5 <author><firstname>William</firstname><surname>Astle</surname></author> 5 <author><firstname>William</firstname><surname>Astle</surname></author>
6 <copyright><year>2009</year><holder>William Astle</holder></copyright> 6 <copyright><year>2009, 2010</year><holder>William Astle</holder></copyright>
7 </bookinfo> 7 </bookinfo>
8 <chapter> 8 <chapter>
9 9
10 <title>Introduction</title> 10 <title>Introduction</title>
11 11
441 </para> 441 </para>
442 442
443 <para> 443 <para>
444 By default, unless assembling to the os9 target, a "$" in the symbol will 444 By default, unless assembling to the os9 target, a "$" in the symbol will
445 also make it local. This can be controlled by the "dollarlocal" and 445 also make it local. This can be controlled by the "dollarlocal" and
446 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, For 446 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, for
447 the os9 target, a "$" in the symbol will not make it considered local while 447 the os9 target, a "$" in the symbol will not make it considered local while
448 for all other targets it will. 448 for all other targets it will.
449 </para> 449 </para>
450 450
451 </section> 451 </section>
758 <para>All conditionals must be fully bracketed. That is, every conditional 758 <para>All conditionals must be fully bracketed. That is, every conditional
759 statement must eventually be followed by an ENDC at the same level of nesting. 759 statement must eventually be followed by an ENDC at the same level of nesting.
760 </para> 760 </para>
761 <para>Conditional expressions are only evaluated on the first assembly pass. 761 <para>Conditional expressions are only evaluated on the first assembly pass.
762 It is not possible to game the assembly process by having a conditional 762 It is not possible to game the assembly process by having a conditional
763 change its value between assembly passes. Thus there is not and never will 763 change its value between assembly passes. Due to the underlying architecture
764 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</para> 764 of LWASM, there is no possible utility to IFP1 and IFP2, nor can they, as of LWASM 3.0, actually
765 be implemented meaningfully. Thus there is not and never will
766 be any equivalent of IFP1 or IFP2 as provided by other assemblers. Use of those opcodes
767 will throw a warning and be ignored.</para>
768
769 <para>It is important to note that if a conditional does not resolve to a constant
770 during the first parsing pass, an error will be thrown. This is unavoidable because the assembler
771 must make a decision about which source to include and which source to exclude at this stage.
772 Thus, expressions that work normally elsewhere will not work for conditions.</para>
765 773
766 <variablelist> 774 <variablelist>
767 <varlistentry> 775 <varlistentry>
768 <term>IFEQ <parameter>expr</parameter></term> 776 <term>IFEQ <parameter>expr</parameter></term>
769 <listitem> 777 <listitem>
939 947
940 <para> 948 <para>
941 Note that the USE variation is provided only for compatibility with other 949 Note that the USE variation is provided only for compatibility with other
942 assemblers. It is recommended to use the INCLUDE variation.</para> 950 assemblers. It is recommended to use the INCLUDE variation.</para>
943 951
952 <para>If <parameter>filename</parameter> begins with a &quot;/&quot;, it is
953 interpreted as an absolute path. If it does not, the search path will be used
954 to find the file. First, the directory containing the file that contains this
955 directive. (Includes within an included file are relative to the included file,
956 not the file that included it.) If the file is not found there, the include path
957 is searched. If it is still not found, an error will be thrown. Note that the
958 current directory as understood by your shell or operating system is not searched.
959 </para>
960
944 </listitem> 961 </listitem>
945 </varlistentry> 962 </varlistentry>
946 963
947 <varlistentry> 964 <varlistentry>
948 <term>END <parameter>[expr]</parameter></term> 965 <term>END <parameter>[expr]</parameter></term>
960 <term>ERROR <parameter>string</parameter></term> 977 <term>ERROR <parameter>string</parameter></term>
961 <listitem> 978 <listitem>
962 <para> 979 <para>
963 Causes a custom error message to be printed at this line. This will cause 980 Causes a custom error message to be printed at this line. This will cause
964 assembly to fail. This directive is most useful inside conditional constructs 981 assembly to fail. This directive is most useful inside conditional constructs
965 to cause assembly to fail if some condition that is known bad happens. 982 to cause assembly to fail if some condition that is known bad happens. Everything
983 from the directive to the end of the line is considered the error message.
984 </para>
985 </listitem>
986 </varlistentry>
987
988 <varlistentry>
989 <term>WARNING <parameter>string</parameter></term>
990 <listitem>
991 <para>
992 Causes a custom warning message to be printed at this line. This will not cause
993 assembly to fail. This directive is most useful inside conditional constructs
994 or include files to alert the programmer to a deprecated feature being used
995 or some other condition that may cause trouble later, but which may, in fact,
996 not cause any trouble.
966 </para> 997 </para>
967 </listitem> 998 </listitem>
968 </varlistentry> 999 </varlistentry>
969 1000
970 <varlistentry> 1001 <varlistentry>
974 This directive is ignored for most output targets. If the output target 1005 This directive is ignored for most output targets. If the output target
975 supports encoding a module name into it, <parameter>string</parameter> 1006 supports encoding a module name into it, <parameter>string</parameter>
976 will be used as the module name. 1007 will be used as the module name.
977 </para> 1008 </para>
978 <para> 1009 <para>
979 As of version 2.2, no supported output targets support this directive. 1010 As of version 3.0, no supported output targets support this directive.
980 </para> 1011 </para>
981 </listitem> 1012 </listitem>
982 </varlistentry> 1013 </varlistentry>
983 1014
984 </variablelist> 1015 </variablelist>
1318 </listitem> 1349 </listitem>
1319 1350
1320 </varlistentry> 1351 </varlistentry>
1321 1352
1322 <varlistentry> 1353 <varlistentry>
1323 <term><parameter>sym</parameter>EXTDEP</term> 1354 <term><parameter>sym</parameter> EXTDEP</term>
1324 <listitem> 1355 <listitem>
1325 1356
1326 <para>This directive forces an external dependency on 1357 <para>This directive forces an external dependency on
1327 <parameter>sym</parameter>, even if it is never referenced anywhere else in 1358 <parameter>sym</parameter>, even if it is never referenced anywhere else in
1328 this file.</para> 1359 this file.</para>