[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: regenerating HACKING
|
From: |
Bruno Haible |
|
Subject: |
Re: regenerating HACKING |
|
Date: |
Sun, 21 Feb 2021 11:09:36 +0100 |
|
User-agent: |
KMail/5.1.3 (Linux/4.4.0-201-generic; KDE/5.18.0; x86_64; ; ) |
> > HACKING:
> > emacs etc/hacking.org --batch -f org-ascii-export-to-ascii --kill
> > mv etc/hacking.txt HACKING
>
> Implemented in the commit below.
Thanks.
Note that the result depends on the emacs version. If I were to regenerate the
file (with emacs 24.5.1), I would get a slightly differently formatted result:
$ diff -u HACKING etc/hacking.txt
--- HACKING 2021-02-21 11:05:32.045089418 +0100
+++ etc/hacking.txt 2021-02-21 11:05:45.713259126 +0100
@@ -9,97 +9,97 @@
Table of Contents
_________________
-1. Nomenclature
-2. Maintenance
-.. 1. Global Maintainer
-.. 2. Global Reviewers
-.. 3. Maintainers
-.. 4. Write After Approval
-.. 5. Personal Branches
-.. 6. Building Release Tarballs
-.. 7. Installing Obvious Changes
-.. 8. The poke.rec database
-.. 9. The source for this HACKING file
-.. 10. The Bugzilla
-..... 1. Dealing with spam in the Bugzilla
-.. 11. Recording noteworthy development changes
-3. Development Environment
-.. 1. Autotools
-.. 2. Dejagnu
-.. 3. Flex
-.. 4. Bison
-.. 5. Jitter
-.. 6. Building
-.. 7. Building after a git pull
-.. 8. Gettext
-.. 9. Running an Uninstalled Poke
-.. 10. Continuous Integration
-4. Coding Style and Conventions
-.. 1. Writing C
-..... 1. Avoid Tabs
-..... 2. Avoid bool
-..... 3. Use _p for Predicates
-..... 4. Documenting Functions in Public Headers
-.. 2. Writing Poke
-.. 3. Writing RAS
-..... 1. RAS Emacs mode
-..... 2. Calling compiled Poke from RAS
-5. Writing Tests
-.. 1. Test framework
-.. 2. Unit Tests
-.. 3. Naming Tests
-.. 4. Always set obase
-.. 5. Put each test in its own file
-.. 6. List the test files in testsuite/Makefile.am
-.. 7. dg-output may require a newline
-.. 8. Using data files in tests
-.. 9. Using NBD connections in tests
-.. 10. Writing tests that depend on a certain capability
-.. 11. Writing REPL tests
-.. 12. Testing Pickles
-..... 1. Command REPL tests
-..... 2. General REPL tests
-6. Writing Documentation
-.. 1. Documenting Pickles
-7. Fuzzing poke
-.. 1. Grammarinator
-8. Submitting a Patch
-9. Maintenance
-10. Poke Architecture
-11. The Poke Compiler
-.. 1. Compiler Overview
-.. 2. The bison Parser in pkl-tab.y
-.. 3. The AST
-..... 1. Loop Statements
-.. 4. Compiler Passes and Phases
-..... 1. Naming Conventions for Phases
-..... 2. Naming Conventions for Handlers
-..... 3. Transformation Phases
-..... 4. Analysis Phases
-..... 5. Type System Phases
-..... 6. Front and Middle End Handlers should be Re-entrant
-.. 5. Adding Compiler Built-Ins
-12. The Poke Virtual Machine
-.. 1. Exception Handling
-.. 2. Signal Handling
-.. 3. Offsets and bit-offsets in the PVM
-13. Memory Management
-.. 1. Using ASTREF
-.. 2. Using ASTDEREF
-.. 3. PVM values in PVM programs
-.. 4. PVM values in AST nodes
-14. Terminal Handling
-.. 1. pk-term
-.. 2. Styling Classes
-.. 3. Debugging Styling
-15. Debugging poke
-.. 1. Building with Debugging support
-.. 2. Invoking GDB to debug an uninstalled poke
-.. 3. Using GDB extensions
-.. 4. Valgrind and Poke
-.. 5. Debugging PVM Assembly Code
-16. Profiling poke
-.. 1. Building with profiling support
+1 Nomenclature
+2 Maintenance
+.. 2.1 Global Maintainer
+.. 2.2 Global Reviewers
+.. 2.3 Maintainers
+.. 2.4 Write After Approval
+.. 2.5 Personal Branches
+.. 2.6 Building Release Tarballs
+.. 2.7 Installing Obvious Changes
+.. 2.8 The poke.rec database
+.. 2.9 The source for this HACKING file
+.. 2.10 The Bugzilla
+..... 2.10.1 Dealing with spam in the Bugzilla
+.. 2.11 Recording noteworthy development changes
+3 Development Environment
+.. 3.1 Autotools
+.. 3.2 Dejagnu
+.. 3.3 Flex
+.. 3.4 Bison
+.. 3.5 Jitter
+.. 3.6 Building
+.. 3.7 Building after a git pull
+.. 3.8 Gettext
+.. 3.9 Running an Uninstalled Poke
+.. 3.10 Continuous Integration
+4 Coding Style and Conventions
+.. 4.1 Writing C
+..... 4.1.1 Avoid Tabs
+..... 4.1.2 Avoid bool
+..... 4.1.3 Use _p for Predicates
+..... 4.1.4 Documenting Functions in Public Headers
+.. 4.2 Writing Poke
+.. 4.3 Writing RAS
+..... 4.3.1 RAS Emacs mode
+..... 4.3.2 Calling compiled Poke from RAS
+5 Writing Tests
+.. 5.1 Test framework
+.. 5.2 Unit Tests
+.. 5.3 Naming Tests
+.. 5.4 Always set obase
+.. 5.5 Put each test in its own file
+.. 5.6 List the test files in testsuite/Makefile.am
+.. 5.7 dg-output may require a newline
+.. 5.8 Using data files in tests
+.. 5.9 Using NBD connections in tests
+.. 5.10 Writing tests that depend on a certain capability
+.. 5.11 Writing REPL tests
+.. 5.12 Testing Pickles
+..... 5.12.1 Command REPL tests
+..... 5.12.2 General REPL tests
+6 Writing Documentation
+.. 6.1 Documenting Pickles
+7 Fuzzing poke
+.. 7.1 Grammarinator
+8 Submitting a Patch
+9 Maintenance
+10 Poke Architecture
+11 The Poke Compiler
+.. 11.1 Compiler Overview
+.. 11.2 The bison Parser in pkl-tab.y
+.. 11.3 The AST
+..... 11.3.1 Loop Statements
+.. 11.4 Compiler Passes and Phases
+..... 11.4.1 Naming Conventions for Phases
+..... 11.4.2 Naming Conventions for Handlers
+..... 11.4.3 Transformation Phases
+..... 11.4.4 Analysis Phases
+..... 11.4.5 Type System Phases
+..... 11.4.6 Front and Middle End Handlers should be Re-entrant
+.. 11.5 Adding Compiler Built-Ins
+12 The Poke Virtual Machine
+.. 12.1 Exception Handling
+.. 12.2 Signal Handling
+.. 12.3 Offsets and bit-offsets in the PVM
+13 Memory Management
+.. 13.1 Using ASTREF
+.. 13.2 Using ASTDEREF
+.. 13.3 PVM values in PVM programs
+.. 13.4 PVM values in AST nodes
+14 Terminal Handling
+.. 14.1 pk-term
+.. 14.2 Styling Classes
+.. 14.3 Debugging Styling
+15 Debugging poke
+.. 15.1 Building with Debugging support
+.. 15.2 Invoking GDB to debug an uninstalled poke
+.. 15.3 Using GDB extensions
+.. 15.4 Valgrind and Poke
+.. 15.5 Debugging PVM Assembly Code
+16 Profiling poke
+.. 16.1 Building with profiling support
Welcome, adventurous poker! This file contains useful information for
@@ -120,7 +120,7 @@
for more details.
You should have received a copy of the GNU General Public License along
-with GNU poke. If not, see <https://www.gnu.org/licenses/>.
+with GNU poke. If not, see [https://www.gnu.org/licenses/].
1 Nomenclature
@@ -168,7 +168,7 @@
messages to the list with the patches they push. This helps to keep
the other hackers aware of what is going on in other areas.
- etc/poke-mode.el Aurélien Aptel <aaptel@suse.com>
+ etc/poke-mode.el Aurélien Aptel <aaptel@suse.com>
2.4 Write After Approval
@@ -178,18 +178,18 @@
install their changes after getting explicit approval from a global
reviewer.
- Egeyar Bagcioglu <egeyar@gmail.com>
- John Darrington <jmd@gnu.org>
- Luca Saiu <positron@gnu.org>
- Darshit Shah <darnir@gnu.org>
- Dan Čermák <dan.cermak@cgc-instruments.com>
- Bruno Haible <bruno@clisp.org>
- Carlo Caione <ccaione@baylibre.com>
- Eric Blake <eblake@redhat.com>
- Tim Ruehsen <tim.ruehsen@gmx.de>
- Kostas Chasialis <sdi1600195@di.uoa.gr>
- Aurélien Aptel <aaptel@suse.com>
- Mohammad-Reza Nabipoor <m.nabipoor@yahoo.com>
+ Egeyar Bagcioglu <egeyar@gmail.com>
+ John Darrington <jmd@gnu.org>
+ Luca Saiu <positron@gnu.org>
+ Darshit Shah <darnir@gnu.org>
+ Dan Čermák <dan.cermak@cgc-instruments.com>
+ Bruno Haible <bruno@clisp.org>
+ Carlo Caione <ccaione@baylibre.com>
+ Eric Blake <eblake@redhat.com>
+ Tim Ruehsen <tim.ruehsen@gmx.de>
+ Kostas Chasialis <sdi1600195@di.uoa.gr>
+ Aurélien Aptel <aaptel@suse.com>
+ Mohammad-Reza Nabipoor <m.nabipoor@yahoo.com>
2.5 Personal Branches
@@ -206,7 +206,6 @@
| jemarch/hyperlinks-server
`----
-
Personal branches are intended to ease the interaction between
developers, and to provide a convenient basis for testing large
changes.
@@ -240,7 +239,7 @@
~~~~~~~~~~~~~~~~~~~~~~~~~
We maintain a database in `etc/poke.rec', in the form of a recfile.
- See <http://www.gnu.org/software/recutils> for more information on
+ See [http://www.gnu.org/software/recutils] for more information on
recfiles.
This database is kept up to date by the maintainer, and contains lots
@@ -264,7 +263,7 @@
2.10 The Bugzilla
~~~~~~~~~~~~~~~~~
- We maintain a bugs database in <https://www.sourceware.org/bugzilla>.
+ We maintain a bugs database in [https://www.sourceware.org/bugzilla].
Our product is `poke', which is divided in several components
corresponding to the several areas of the program/project.
@@ -321,7 +320,7 @@
are getting the sources from git (or change configure.ac), you'll need
to have these tools installed to (re)build. You'll also need
help2man. All of these programs are available from
- <ftp://ftp.gnu.org/gnu>.
+ [ftp://ftp.gnu.org/gnu].
3.2 Dejagnu
@@ -352,7 +351,7 @@
~~~~~~~~~~
In order to build and run poke, you need Luca Saiu's jitter. Jitter
- is available at <http://ageinghacker.net/git/cgit.cgi/jitter>.
+ is available at [http://ageinghacker.net/git/cgit.cgi/jitter].
The appropriate version of Jitter is now downloaded and bootstrapped
automatically by Poke's `bootstrap' script, which frees the user from
@@ -374,7 +373,6 @@
| $ ./bootstrap --skip-po
`----
-
Then, you can run `configure', as described in the files INSTALL and
INSTALL.generic. For example:
@@ -383,7 +381,6 @@
| $ ../configure
`----
-
Finally:
,----
@@ -460,7 +457,7 @@
~~~~~~~~~~~~~
In Poke we follow the GNU Coding Standards. Please see
- <https://www.gnu.org/prep/standards/>.
+ [https://www.gnu.org/prep/standards/].
Additionally, we have a few conventions that we ask you to follow when
hacking poke, in order to keep a coherent style when possible. These
@@ -548,7 +545,6 @@
| 16#B
`----
-
instead of:
,----
@@ -591,7 +587,6 @@
| }
`----
-
Then, the function can be invoked from the hand-written RAS file using
the `.call' directive:
@@ -599,7 +594,6 @@
| .call _pkl_foo
`----
-
Note how the compiler internal functions use the `_pkl_' prefix. Also
note that `.call' can only invoke functions defined in the global
environment.
@@ -617,11 +611,11 @@
The test suite is based on DejaGnu, for which you find the general
documentation at
- <https://www.gnu.org/software/dejagnu/manual/index.html>
+ [https://www.gnu.org/software/dejagnu/manual/index.html]
The documentation of specific DejaGnu directives is at
- <https://gcc.gnu.org/onlinedocs/gccint/Directives.html>
- <https://gcc.gnu.org/wiki/HowToPrepareATestcase>
+ [https://gcc.gnu.org/onlinedocs/gccint/Directives.html]
+ [https://gcc.gnu.org/wiki/HowToPrepareATestcase]
5.2 Unit Tests
@@ -653,7 +647,6 @@
| /* { dg-command {.set obase 10} } */
`----
-
This way, we won't have to change the tests if at some point we change
the default obase.
@@ -677,7 +670,6 @@
| [... and so on ...]
`----
-
However, this is not a good idea. If some of the "subtests" fail, it
becomes difficult to determine which one is the culprit looking at the
test log file.
@@ -723,7 +715,6 @@
| /* { dg-data {c*} {0x10 0x20 0x30 0x40 ...} } */
`----
-
This creates a temporary file (whose name is irrelevant) and makes it
the current IO space at poke initialization time. The test body, and
dg-commands, can then map on it.
@@ -741,7 +732,6 @@
| /* { dg-command { var foo = open ("foo.data") } } */
`----
-
The file created by the last dg-data (be it anonymous or named) is the
current IO space.
@@ -756,7 +746,6 @@
| /* { dg-nbd { 0x1 0x2 ...} [dg-tmpdir]/sock } */
`----
-
This utilizes nbdkit to serve an in-memory disk with initial contents
over a named Unix socket. Note that the data argument is not the same
as for dg-data (which uses tcl's binary command), but rather the
@@ -794,16 +783,13 @@
| /* { dg-output "<span class=\"foo\">10</span>" } */
`----
-
IMPORTANT NOTE: dg-require should appear before any dg-command
directive in the test file.
The supported capabilities are:
- libtextstyle
- poke is built with libtextstyle support.
- nbd
- poke is built with NBD io space support, and dg-nbd works.
+ libtextstyle: poke is built with libtextstyle support.
+ nbd: poke is built with NBD io space support, and dg-nbd works.
5.11 Writing REPL tests
@@ -814,19 +800,17 @@
it uses the services provided by `testsuite/lib/poke.exp'. In a
nutshell, these services are:
- poke_start
- Run a new poke process and wait at the prompt.
- poke_exit
- Exit poke.
- poke_test_cmd CMD PATTERN
- Send CMD to poke, and expect the result PATTERN. CMD is sent as
- virtual keystrokes. Therefore, sending \t or \n has the same
- effect on the REPL than typing TAB or RET in the keyboard,
- respectively. PATTERN shouldn't include the prompt.
- poke_send INPUT PATTERN
- Send INPUT to poke, and expect PATTERN as output.
- poke_send_signal SIGNAL
- Send SIGNAL to poke.
+ poke_start: Run a new poke process and wait at the prompt.
+ poke_exit: Exit poke.
+ poke_test_cmd CMD PATTERN: Send CMD to poke, and expect the result
+ PATTERN. CMD is sent as virtual keystrokes.
+ Therefore, sending \t or \n has the same
+ effect on the REPL than typing TAB or RET in
+ the keyboard, respectively. PATTERN
+ shouldn't include the prompt.
+ poke_send INPUT PATTERN: Send INPUT to poke, and expect PATTERN as
+ output.
+ poke_send_signal SIGNAL: Send SIGNAL to poke.
Adding a new test to `poke.repl' involves editing `poke.repl/repl.exp'
and adding some content there. The following subsections detail how.
@@ -860,7 +844,6 @@
| poke_exit
`----
-
The snippet above implements a test named "slashes are preserved" that
runs poke and sends the command `4 / 2' with expected result `2'.
@@ -887,7 +870,6 @@
| poke_exit
`----
-
The test above uses the `poke_send' procedure, defined in
`testsuite/lib/poke.exp'. This procedure gets two arguments: the
input that is sent to poke, and the expected output. Note how usign
@@ -938,7 +920,6 @@
| $ sudo python3 setup.py install
`----
-
Then, use `grammarinator-process' in order to create the "unparser"
and "unlexer" for poke:
@@ -946,7 +927,6 @@
| $ grammarinator-process ../path/to/poke.g4
`----
-
This will create two files in the current working directory:
`pokeUnlexer.py' and `pokeUnparser.py'. Next step is to use
`grammarinator-generate' in order to create tests:
@@ -957,7 +937,6 @@
| -t grammarinator.runtime.simple_space_transformer
`----
-
The option `-n' specifies the number of tests (Poke programs) to
generate.
@@ -1011,38 +990,37 @@
This section describes `make' targets that performs several
maintenance tasks.
- syntax-check
- Run several syntax-related checks in the source files. It is
- useful to run this target before submitting code to be reviewed,
- and while reviewing other people's code.
-
- Note that sometimes the results have to be taken with a pinch of
- salt. This happens, for example, when a rule oriented to C is
- applied to, say, an AWK file. In these cases, consider adding a
- `.x-sc_*' fine-tuning file. But please ask in poke-devel first.
-
- We provide a pre-push git hook that performs the syntax check
- right before pushing. If the check fails, the push is
- aborted. You should consider enabling this check by coping
- `etc/git-hooks/pre-push' to `.git/hooks/'.
- coverage
- This target builds *poke* with code coverage support, runs the
- testsuite, and generates a nice html report under
- `$(top_builddir)/doc/coverage/'. It is necessary to have the
- `lcov' program for this to work.
- cyclo-poke.html
- This target runs the pmccabe utility to calculate the modified
- cyclomatic complexity of the functions composing the poke
- sources, and generates a nice html report.
- refresh-po
- This target download the latest available translations from the
- translation project and installs them in the source tree.
- update-copyright
- Run this rule once per year (usually early in January) to update
- all the copyright years in the project. By default this
- excludes all variants of COPYING. Exceptions to this procedure
- (such as `ChangeLog..*' for rotated change logs) can be added in
- the file `.x-update-copyright'.
+ syntax-check: Run several syntax-related checks in the source files.
+ It is useful to run this target before submitting code to
+ be reviewed, and while reviewing other people's code.
+
+ Note that sometimes the results have to be taken with a
+ pinch of salt. This happens, for example, when a rule
+ oriented to C is applied to, say, an AWK file. In these
+ cases, consider adding a `.x-sc_*' fine-tuning file. But
+ please ask in poke-devel first.
+
+ We provide a pre-push git hook that performs the syntax
+ check right before pushing. If the check fails, the push
+ is aborted. You should consider enabling this check by
+ coping `etc/git-hooks/pre-push' to `.git/hooks/'.
+ coverage: This target builds *poke* with code coverage support, runs
+ the testsuite, and generates a nice html report under
+ `$(top_builddir)/doc/coverage/'. It is necessary to have the
+ `lcov' program for this to work.
+ cyclo-poke.html: This target runs the pmccabe utility to calculate
+ the modified cyclomatic complexity of the functions
+ composing the poke sources, and generates a nice html
+ report.
+ refresh-po: This target download the latest available translations
+ from the translation project and installs them in the source
+ tree.
+ update-copyright: Run this rule once per year (usually early in
+ January) to update all the copyright years in the
+ project. By default this excludes all variants of
+ COPYING. Exceptions to this procedure (such as
+ `ChangeLog..*' for rotated change logs) can be added
+ in the file `.x-update-copyright'.
10 Poke Architecture
@@ -1156,7 +1134,6 @@
| +-- body
`----
-
Different kind of loop statements supported in Poke are represented
including or not including optional fields.
@@ -1166,7 +1143,6 @@
| while (CONDITION) BODY
`----
-
are represented as:
,----
@@ -1176,14 +1152,12 @@
| +-- body
`----
-
`while' statements without a condition:
,----
| while () BODY
`----
-
are represented as:
,----
@@ -1192,14 +1166,12 @@
| +-- body
`----
-
`for-in' statements:
,----
| for (VAR in CONTAINER) BODY
`----
-
are represented as:
,----
@@ -1213,14 +1185,12 @@
| +-- body
`----
-
`for-in-where' statements:
,----
| for (VAR in CONTAINER where SELECTOR) BODY
`----
-
are represented as:
,----
@@ -1263,12 +1233,9 @@
The phases above are organized in several passes:
- Pass1
- trans1 anal1 typify1 promo trans2 fold trans3 typify2 anal2
- Pass2
- fold trans4 analf
- Pass3
- gen
+ Pass1: trans1 anal1 typify1 promo trans2 fold trans3 typify2 anal2
+ Pass2: fold trans4 analf
+ Pass3: gen
11.4.1 Naming Conventions for Phases
@@ -1280,7 +1247,6 @@
| {NAME}{SUFFIX}
`----
-
where `NAME' reflects a phase category (see below) and `SUFFIX' is
usually an integer that specifies the order in which the phases are
applied. Thus, for example, `name4' is performed after `name1'.
@@ -1291,27 +1257,22 @@
We use the following phase categories:
- anal
- For phases whose main purpose is to perform checks on the AST,
- and/or the contents of the AST nodes, and emit errors/warnings.
- trans
- For phases whose main purpose is to alter the structure of the
- AST, and/or the contents of the AST nodes.
- typify
- For phases whose main purpose is to perform type checks, and
- otherwise do work on types.
- promo
- For phases whose main purpose is to perform coercions wherever
- appropriate. Currently there is only one phase in this
- category.
- fold
- For phases whose main purpose is to pre-compute areas of the AST
- whenever it is possible to do so at compile-time. Currently
+ anal: For phases whose main purpose is to perform checks on the
+ AST, and/or the contents of the AST nodes, and emit
+ errors/warnings.
+ trans: For phases whose main purpose is to alter the structure of
+ the AST, and/or the contents of the AST nodes.
+ typify: For phases whose main purpose is to perform type checks,
+ and otherwise do work on types.
+ promo: For phases whose main purpose is to perform coercions
+ wherever appropriate. Currently there is only one phase in this
+ category.
+ fold: For phases whose main purpose is to pre-compute areas of the
+ AST whenever it is possible to do so at compile-time. Currently
there is only one phase in this category, that performs constant
folding.
- gen
- For phases whose main purpose is to generate PVM code.
- Currently there is only one phase in this category.
+ gen: For phases whose main purpose is to generate PVM code.
+ Currently there is only one phase in this category.
The phases in category `NAME' are implemented in the source files
`libpoke/pkl-NAME.[ch]'.
@@ -1326,7 +1287,6 @@
| pkl_PHASE_{ps,pr}_NODE
`----
-
where `PHASE' can be a complete phase name (like `typify1') if the
handler is to be installed in that phase only, or a phase category
name (like `typify') if the handler is to be installed in several
@@ -1340,7 +1300,6 @@
| pkl_anal1_ps_comp_stmt
`----
-
is installed in the phase `anal1', executes in post-order, and serves
the AST nodes with code `PKL_AST_COMP_STMT'.
@@ -1348,136 +1307,131 @@
11.4.3 Transformation Phases
----------------------------
- trans1
- - Finishes strings by expanding sequences, emitting diagnostics
- if an invalid sequence is found.
- - Computes and set the number of elements in STRUCT nodes.
- - Computes and sets the number of elements, fields and
- declarations in struct TYPE nodes.
- - Completes offsets with implicit magnitude by adding a
- magnitude of int<32>1.
- - Calculates the number of arguments in FUNCALL nodes.
- - Annotates declaration nodes as being directly contained in
- struct type nodes.
- - Annotates variables that refer to recursive function calls as
- recursive.
- - Annotates variables with the enclosing function, and with
- their lexical nesting level with respect the beginning of the
- enclosing function.
- - Variables that refer to parameterless functions are
- transformed into funcalls to these functions.
- - Finalizes ATTR node by determining the operation corresponding
- to the attribute name, turning the IDENTIFIERxEXP binary
- expression into an unary expression.
- - Annotates a function's first optional argument and the number
- of formal arguments.
- - Completes function types with their number of formal
- arguments, annotates its first optional argument, and
- determines whether the function type gets a vararg.
- - Completes trimmers with implicit indexes, i.e. [N:], [:N] or
- [:], by adding the missing index as an appropriate expression.
- - Decodes format strings in printf statements.
- - Computes and sets the indexes of all the elements of an ARRAY
- node (array literal) and sets the size of the array.
- - Annotates compound statements with the number of variable and
- function declarations occurring within the statement.
- trans2
- - Annotates expression nodes that are literals, i.e. expressions
- whose values can be computed at compile-time.
- - Annotates offsets, arrays, indexers, trimmers, structs, struct
- references, and casts as literals.
- - Turn struct references that refer to parameterless methods
- into funcalls to these methods.
- - In offsets whose units are type names, make sure these types
- are complete and replace the unit with an expression that
- evaluates to the size of the unit type, in bits.
- trans3
- - SIZEOF nodes whose operand is a complete type are replaced
- with an offset.
+ trans1:
+ - Finishes strings by expanding sequences, emitting diagnostics if
+ an invalid sequence is found.
+ - Computes and set the number of elements in STRUCT nodes.
+ - Computes and sets the number of elements, fields and declarations
+ in struct TYPE nodes.
+ - Completes offsets with implicit magnitude by adding a magnitude of
+ int<32>1.
+ - Calculates the number of arguments in FUNCALL nodes.
+ - Annotates declaration nodes as being directly contained in struct
+ type nodes.
+ - Annotates variables that refer to recursive function calls as
+ recursive.
+ - Annotates variables with the enclosing function, and with their
+ lexical nesting level with respect the beginning of the enclosing
+ function.
+ - Variables that refer to parameterless functions are transformed
+ into funcalls to these functions.
+ - Finalizes ATTR node by determining the operation corresponding to
+ the attribute name, turning the IDENTIFIERxEXP binary expression
+ into an unary expression.
+ - Annotates a function's first optional argument and the number of
+ formal arguments.
+ - Completes function types with their number of formal arguments,
+ annotates its first optional argument, and determines whether the
+ function type gets a vararg.
+ - Completes trimmers with implicit indexes, i.e. [N:], [:N] or [:],
+ by adding the missing index as an appropriate expression.
+ - Decodes format strings in printf statements.
+ - Computes and sets the indexes of all the elements of an ARRAY node
+ (array literal) and sets the size of the array.
+ - Annotates compound statements with the number of variable and
+ function declarations occurring within the statement.
+ trans2:
+ - Annotates expression nodes that are literals, i.e. expressions
+ whose values can be computed at compile-time.
+ - Annotates offsets, arrays, indexers, trimmers, structs, struct
+ references, and casts as literals.
+ - Turn struct references that refer to parameterless methods into
+ funcalls to these methods.
+ - In offsets whose units are type names, make sure these types are
+ complete and replace the unit with an expression that evaluates to
+ the size of the unit type, in bits.
+ trans3:
+ - SIZEOF nodes whose operand is a complete type are replaced with an
+ offset.
11.4.4 Analysis Phases
----------------------
- anal1
- - Checks that the elements in struct literals have unique names.
- - Checks that the elements in struct types have unique names.
- - Checks that declarations in unions appear before any of the
- alternatives.
- - Checks that builtin compound statements don't contain
- statements.
- - Check that the actual arguments passed to a funcall are all
- either named or none named.
- - Check that named arguments to funcalls are passed only once.
- - Check that all optional formal arguments in a function
- specifier are located at the end of the arguments list.
- - Check that function specifiers have at most one vararg
- argument, and that it is located at the end of the formal
- arguments list.
- - Check that function types have at most one vararg argument,
- and that it is located at the end of the formal arguments
- list.
- - Check that every BREAK statement have a containing statement.
- - Check that every RETURN statement have a containing function.
- - If the unit in an offset type specifier is specified using an
- integral constant, this constant should be bigger than zero.
- - The unit of an offset literal, if expressed as an integral,
- shall be bigger than zero.
- - Check that the bit count operator in left shift operations are
- less than the number of bits of the shifted operand. This is
- checked in cases where the bit count is constant.
- - Methods can only be defined in a struct type.
- - The initializing expressions in unit declarations should be
- integer nodes.
- - Only methods can call other methods.
- - Methods are not allowed to refer to variables and functions
- defined in struct types.
- - A method can only refer to struct fields and methods defined
- in the same struct type.
- - Functions recursively defined inside methods are not allowed
- to refer to struct fields and methods.
- - Only methods can assign struct fields as variables.
- anal2
- - Every expression, array and struct node should be annotated
- with a type, and the type's completeness should have been
- determined.
- - The magnitude in offset literals should be an integral
- expression.
- - The magnitude in offset literals should have a type and its
- completeness should be known.
- - A return statement returning a value is not allowed in a void
- function.
- - An expressionless return statement is invalid in a non-void
- function.
- - A funcall to a void function is only allowed in an
- expression-statement.
- - Endianness specifiers in struct fields are only valid when
- applied to integral types.
- - In unions, alternatives appearing after an alternative with no
- constraint expression, or a constant expression known to be
- true, are unreachable. Warn about this.
- - If an union alternative has a constraint known to be false, it
- is never taken. Warn about this.
- - Optional fields are not supported in unions.
- - The indexes in array initializers should be constant.
- analf
- - Every array initializer should have an index.
- - Check that the left-hand side of assignment statements are of
- the right kind.
+ anal1:
+ - Checks that the elements in struct literals have unique names.
+ - Checks that the elements in struct types have unique names.
+ - Checks that declarations in unions appear before any of the
+ alternatives.
+ - Checks that builtin compound statements don't contain statements.
+ - Check that the actual arguments passed to a funcall are all either
+ named or none named.
+ - Check that named arguments to funcalls are passed only once.
+ - Check that all optional formal arguments in a function specifier
+ are located at the end of the arguments list.
+ - Check that function specifiers have at most one vararg argument,
+ and that it is located at the end of the formal arguments list.
+ - Check that function types have at most one vararg argument, and
+ that it is located at the end of the formal arguments list.
+ - Check that every BREAK statement have a containing statement.
+ - Check that every RETURN statement have a containing function.
+ - If the unit in an offset type specifier is specified using an
+ integral constant, this constant should be bigger than zero.
+ - The unit of an offset literal, if expressed as an integral, shall
+ be bigger than zero.
+ - Check that the bit count operator in left shift operations are
+ less than the number of bits of the shifted operand. This is
+ checked in cases where the bit count is constant.
+ - Methods can only be defined in a struct type.
+ - The initializing expressions in unit declarations should be
+ integer nodes.
+ - Only methods can call other methods.
+ - Methods are not allowed to refer to variables and functions
+ defined in struct types.
+ - A method can only refer to struct fields and methods defined in
+ the same struct type.
+ - Functions recursively defined inside methods are not allowed to
+ refer to struct fields and methods.
+ - Only methods can assign struct fields as variables.
+ anal2:
+ - Every expression, array and struct node should be annotated with a
+ type, and the type's completeness should have been determined.
+ - The magnitude in offset literals should be an integral expression.
+ - The magnitude in offset literals should have a type and its
+ completeness should be known.
+ - A return statement returning a value is not allowed in a void
+ function.
+ - An expressionless return statement is invalid in a non-void
+ function.
+ - A funcall to a void function is only allowed in an
+ expression-statement.
+ - Endianness specifiers in struct fields are only valid when applied
+ to integral types.
+ - In unions, alternatives appearing after an alternative with no
+ constraint expression, or a constant expression known to be true,
+ are unreachable. Warn about this.
+ - If an union alternative has a constraint known to be false, it is
+ never taken. Warn about this.
+ - Optional fields are not supported in unions.
+ - The indexes in array initializers should be constant.
+ analf:
+ - Every array initializer should have an index.
+ - Check that the left-hand side of assignment statements are of the
+ right kind.
11.4.5 Type System Phases
-------------------------
- typify1
- - Checks that the expression in which a funcall is applied is a
- function, and that the types of the formal parameters mach the
- types of the funcall arguments.
- - Checks that void functions are not called in contexts where a
- value is expected.
- typify2
- - Checks that the type of the expression in a return statement
- matches the return type of its containing function.
+ typify1:
+ - Checks that the expression in which a funcall is applied is a
+ function, and that the types of the formal parameters mach the
+ types of the funcall arguments.
+ - Checks that void functions are not called in contexts where a
+ value is expected.
+ typify2:
+ - Checks that the type of the expression in a return statement
+ matches the return type of its containing function.
11.4.6 Front and Middle End Handlers should be Re-entrant
@@ -1489,7 +1443,6 @@
| Foo @ 0#B
`----
-
The AST associated with the type is processed again thru the compiler
middle-end phases. This means that if a handler modifies an AST
subtree, it should either do it in a way the new structure will be
@@ -1516,7 +1469,6 @@
| "__PKL_BUILTIN_RAND__" { return BUILTIN_RAND; }
`----
-
Then, add a new rule to the rule `comp_stmt' in the bison parser.
Built-ins are equivalent to compound statements. For example, this is
the rule for the rand built-in:
@@ -1533,7 +1485,6 @@
| }
`----
-
Next step is to generate the code for the built-in. This is done
expanding the `pkl_gen_ps_comp_stmt' rule in the code generation.
Keep in mind that the generated code should conform a valid function
@@ -1546,13 +1497,11 @@
| break;
`----
-
,----
| The final step is to define the built-in function proper, in the
| compiler run-time, in =pkl-rt.pk=:
`----
-
,----
| fun rand = int<32>: __PKL_BUILTIN_RAND__;
`----
@@ -1673,7 +1622,6 @@
| pkl_ast_node foo = ASTREF (node);
`----
-
Note that the `pkl_ast_make_*' constructors do `ASTREF' internally, so
you don't need to use it in calls like:
@@ -1681,7 +1629,6 @@
| pkl_ast_node new = pkl_ast_make_struct (ast, 5, elems_node);
`----
-
To make sure you get the reference counting right, it's required to
use the return value of `ASTREF' function. The compiler will warn you
otherwise.
@@ -1708,7 +1655,6 @@
| PKL_AST_KIND_WHAT (node) = ASTREF (x);
`----
-
This works because `pkl_ast_make_xxx' does an `ASTREF' to `b'
internally. The final result is that the reference counter of `b'
doesn't change at all.
@@ -1732,7 +1678,6 @@
| regvar $eidx
`----
-
There is only one place where jitter routines are stored in other data
structures: the PVM program abstraction.
@@ -1747,7 +1692,6 @@
| }
`----
-
However, since `routine' is malloc-allocated, the GC can't traverse
it. Consequently, the references to contained boxed values won't be
accounted for, and these values will be collected if there are no more
@@ -1766,7 +1710,6 @@
| };
`----
-
The pointers are collected in the `pvm-program.c' functions that
append parameters to instructions.
@@ -1881,7 +1824,6 @@
| pk_term_end_class ("foo");
`----
-
The `class' and `end_class' calls should be properly paired.
The styling classes used in poke should be documented in the user
@@ -1995,7 +1937,6 @@
| $ valgrind --tool=memcheck --gen-suppressions=all --log-file=raw.log
`----
-
Then process raw.log with the `etc/parse-valgrind-suppressions.sh'
script, wildcard the result as much as you can, and append the results
to `etc/boehm-gc.suppressions'.
@@ -2009,7 +1950,6 @@
| --tool=memcheck --gen-suppressions=all"
`----
-
Then run `make check' as usual.
@@ -2026,7 +1966,6 @@
| pkl_asm_insn (pasm, PKL_INSN_NIP2);
`----
-
Or, alternatively, the code may be written in RAS in a `.pks' file.
Like:
@@ -2039,7 +1978,6 @@
| ba .loop
`----
-
Often, a run-time problem becomes apparent while the PVM executes the
generated code. Typical cases are when a PVM value doesn't contain
what it's supposed to contain, and accessing the wrong boxed value
@@ -2072,7 +2010,6 @@
| ba .loop
`----
-
The other tool is the `strace' instruction. It prints the contents of
the stack (one value per line) from the TOS. It gets the number of
stack values to print as an argument, 0 meaning all of them. It is
@@ -2093,7 +2030,6 @@
| pkl_asm_insn (pasm, PKL_INSN_NIP2);
`----
-
We recompile, re-run, and we find out that the elements at the TOS
when `mullu' is executed are a pair of stupid signed integers, which
are not boxed and not what the instruction expects. Mystery solved.
@@ -2113,7 +2049,6 @@
| .vm profile show
`----
-
For these commands to work you need to build poke with profiling
support. This is done by passing the `--enable-pvm-profiling' command
line option to `configure'.