diff --git a/doc/apis.txt b/doc/apis.txt index 165279490e..277c1925b9 100644 --- a/doc/apis.txt +++ b/doc/apis.txt @@ -20,7 +20,7 @@ English word To use Notes ------------------- ------------ -------------------------------------- initialize initT ``init`` is used to create a value type ``T`` -new newP ``new`` is used to create a +new newP ``new`` is used to create a reference type ``P`` find find should return the position where something was found; for a bool result diff --git a/doc/docs.txt b/doc/docs.txt index ecf0cc2682..4484784ae2 100644 --- a/doc/docs.txt +++ b/doc/docs.txt @@ -28,7 +28,7 @@ The documentation consists of several documents: builtin templating system. - | `Term rewriting macros `_ - | Term rewriting macros enhance the compilation process with user defined + | Term rewriting macros enhance the compilation process with user defined optimizations. - | `Internal documentation `_ diff --git a/doc/endb.txt b/doc/endb.txt index 049f9d40df..6757d98e31 100644 --- a/doc/endb.txt +++ b/doc/endb.txt @@ -1,203 +1,203 @@ -============================================== - Embedded Nim Debugger (ENDB) User Guide -============================================== - -:Author: Andreas Rumpf -:Version: |nimversion| - -.. contents:: - +============================================== + Embedded Nim Debugger (ENDB) User Guide +============================================== + +:Author: Andreas Rumpf +:Version: |nimversion| + +.. contents:: + **WARNING**: ENDB is not maintained anymore! Please help if you're interested in this tool. - -Nim comes with a platform independent debugger - -the Embedded Nim Debugger (ENDB). The debugger is -*embedded* into your executable if it has been -compiled with the ``--debugger:on`` command line option. -This also defines the conditional symbol ``ENDB`` for you. - -Note: You must not compile your program with the ``--app:gui`` -command line option because then there would be no console -available for the debugger. - -If you start your program the debugger will immediately show -a prompt on the console. You can now enter a command. The next sections -deal with the possible commands. As usual in Nim in all commands -underscores and case do not matter. Optional components of a command -are listed in brackets ``[...]`` here. - - -General Commands -================ - -``h``, ``help`` - Display a quick reference of the possible commands. - -``q``, ``quit`` - Quit the debugger and the program. - - - (Without any typed command) repeat the previous debugger command. - If there is no previous command, ``step_into`` is assumed. - -Executing Commands -================== - -``s``, ``step_into`` - Single step, stepping into routine calls. - -``n``, ``step_over`` - Single step, without stepping into routine calls. - -``f``, ``skip_current`` - Continue execution until the current routine finishes. - -``c``, ``continue`` - Continue execution until the next breakpoint. - -``i``, ``ignore`` - Continue execution, ignore all breakpoints. This effectively quits - the debugger and runs the program until it finishes. - - -Breakpoint Commands -=================== - -``b``, ``setbreak`` [fromline [toline]] [file] - Set a new breakpoint for the given file - and line numbers. If no file is given, the current execution point's - filename is used. If the filename has no extension, ``.nim`` is - appended for your convenience. - If no line numbers are given, the current execution point's - line is used. If both ``fromline`` and ``toline`` are given the - breakpoint contains a line number range. Some examples if it is still - unclear: - - * ``b 12 15 thallo`` creates a breakpoint that - will be triggered if the instruction pointer reaches one of the - lines 12-15 in the file ``thallo.nim``. - * ``b 12 thallo`` creates a breakpoint that - will be triggered if the instruction pointer reaches the - line 12 in the file ``thallo.nim``. - * ``b 12`` creates a breakpoint that - will be triggered if the instruction pointer reaches the - line 12 in the current file. - * ``b`` creates a breakpoint that - will be triggered if the instruction pointer reaches the - current line in the current file again. - -``breakpoints`` - Display the entire breakpoint list. - -``disable`` - Disable a breakpoint. It remains disabled until you turn it on again - with the ``enable`` command. - -``enable`` - Enable a breakpoint. - -Often it happens when debugging that you keep retyping the breakpoints again -and again because they are lost when you restart your program. This is not -necessary: A special pragma has been defined for this: - - -The ``breakpoint`` pragma -------------------------- - -The ``breakpoint`` pragma is syntactically a statement. It can be used -to mark the *following line* as a breakpoint: - -.. code-block:: Nim - write("1") - {.breakpoint: "before_write_2".} - write("2") - -The name of the breakpoint here is ``before_write_2``. Of course the -breakpoint's name is optional - the compiler will generate one for you -if you leave it out. - -Code for the ``breakpoint`` pragma is only generated if the debugger -is turned on, so you don't need to remove it from your source code after -debugging. - - -The ``watchpoint`` pragma -------------------------- - -The ``watchpoint`` pragma is syntactically a statement. It can be used -to mark a location as a watchpoint: - -.. code-block:: Nim - var a: array [0..20, int] - - {.watchpoint: a[3].} - for i in 0 .. 20: a[i] = i - -ENDB then writes a stack trace whenever the content of the location ``a[3]`` -changes. The current implementation only tracks a hash value of the location's -contents and so locations that are not word sized may encounter false -negatives in very rare cases. - -Code for the ``watchpoint`` pragma is only generated if the debugger -is turned on, so you don't need to remove it from your source code after -debugging. - -Due to the primitive implementation watchpoints are even slower than -breakpoints: After *every* executed Nim code line it is checked whether the -location changed. - - -Data Display Commands -===================== - -``e``, ``eval`` - Evaluate the expression . Note that ENDB has no full-blown expression - evaluator built-in. So expressions are limited: - - * To display global variables prefix their names with their - owning module: ``nim1.globalVar`` - * To display local variables or parameters just type in - their name: ``localVar``. If you want to inspect variables that are not - in the current stack frame, use the ``up`` or ``down`` command. - - Unfortunately, only inspecting variables is possible at the moment. Maybe - a future version will implement a full-blown Nim expression evaluator, - but this is not easy to do and would bloat the debugger's code. - - Since displaying the whole data structures is often not needed and - painfully slow, the debugger uses a *maximal display depth* concept for - displaying. - - You can alter the maximal display depth with the ``maxdisplay`` - command. - -``maxdisplay`` - Sets the maximal display depth to the given integer value. A value of 0 - means there is no maximal display depth. Default is 3. - -``o``, ``out`` - Evaluate the expression and store its string representation into a - file named . If the file does not exist, it will be created, - otherwise it will be opened for appending. - -``w``, ``where`` - Display the current execution point. - -``u``, ``up`` - Go up in the call stack. - -``d``, ``down`` - Go down in the call stack. - -``stackframe`` [file] - Displays the content of the current stack frame in ``stdout`` or - appends it to the file, depending on whether a file is given. - -``callstack`` - Display the entire call stack (but not its content). - -``l``, ``locals`` - Display the available local variables in the current stack frame. - -``g``, ``globals`` - Display all the global variables that are available for inspection. + +Nim comes with a platform independent debugger - +the Embedded Nim Debugger (ENDB). The debugger is +*embedded* into your executable if it has been +compiled with the ``--debugger:on`` command line option. +This also defines the conditional symbol ``ENDB`` for you. + +Note: You must not compile your program with the ``--app:gui`` +command line option because then there would be no console +available for the debugger. + +If you start your program the debugger will immediately show +a prompt on the console. You can now enter a command. The next sections +deal with the possible commands. As usual in Nim in all commands +underscores and case do not matter. Optional components of a command +are listed in brackets ``[...]`` here. + + +General Commands +================ + +``h``, ``help`` + Display a quick reference of the possible commands. + +``q``, ``quit`` + Quit the debugger and the program. + + + (Without any typed command) repeat the previous debugger command. + If there is no previous command, ``step_into`` is assumed. + +Executing Commands +================== + +``s``, ``step_into`` + Single step, stepping into routine calls. + +``n``, ``step_over`` + Single step, without stepping into routine calls. + +``f``, ``skip_current`` + Continue execution until the current routine finishes. + +``c``, ``continue`` + Continue execution until the next breakpoint. + +``i``, ``ignore`` + Continue execution, ignore all breakpoints. This effectively quits + the debugger and runs the program until it finishes. + + +Breakpoint Commands +=================== + +``b``, ``setbreak`` [fromline [toline]] [file] + Set a new breakpoint for the given file + and line numbers. If no file is given, the current execution point's + filename is used. If the filename has no extension, ``.nim`` is + appended for your convenience. + If no line numbers are given, the current execution point's + line is used. If both ``fromline`` and ``toline`` are given the + breakpoint contains a line number range. Some examples if it is still + unclear: + + * ``b 12 15 thallo`` creates a breakpoint that + will be triggered if the instruction pointer reaches one of the + lines 12-15 in the file ``thallo.nim``. + * ``b 12 thallo`` creates a breakpoint that + will be triggered if the instruction pointer reaches the + line 12 in the file ``thallo.nim``. + * ``b 12`` creates a breakpoint that + will be triggered if the instruction pointer reaches the + line 12 in the current file. + * ``b`` creates a breakpoint that + will be triggered if the instruction pointer reaches the + current line in the current file again. + +``breakpoints`` + Display the entire breakpoint list. + +``disable`` + Disable a breakpoint. It remains disabled until you turn it on again + with the ``enable`` command. + +``enable`` + Enable a breakpoint. + +Often it happens when debugging that you keep retyping the breakpoints again +and again because they are lost when you restart your program. This is not +necessary: A special pragma has been defined for this: + + +The ``breakpoint`` pragma +------------------------- + +The ``breakpoint`` pragma is syntactically a statement. It can be used +to mark the *following line* as a breakpoint: + +.. code-block:: Nim + write("1") + {.breakpoint: "before_write_2".} + write("2") + +The name of the breakpoint here is ``before_write_2``. Of course the +breakpoint's name is optional - the compiler will generate one for you +if you leave it out. + +Code for the ``breakpoint`` pragma is only generated if the debugger +is turned on, so you don't need to remove it from your source code after +debugging. + + +The ``watchpoint`` pragma +------------------------- + +The ``watchpoint`` pragma is syntactically a statement. It can be used +to mark a location as a watchpoint: + +.. code-block:: Nim + var a: array [0..20, int] + + {.watchpoint: a[3].} + for i in 0 .. 20: a[i] = i + +ENDB then writes a stack trace whenever the content of the location ``a[3]`` +changes. The current implementation only tracks a hash value of the location's +contents and so locations that are not word sized may encounter false +negatives in very rare cases. + +Code for the ``watchpoint`` pragma is only generated if the debugger +is turned on, so you don't need to remove it from your source code after +debugging. + +Due to the primitive implementation watchpoints are even slower than +breakpoints: After *every* executed Nim code line it is checked whether the +location changed. + + +Data Display Commands +===================== + +``e``, ``eval`` + Evaluate the expression . Note that ENDB has no full-blown expression + evaluator built-in. So expressions are limited: + + * To display global variables prefix their names with their + owning module: ``nim1.globalVar`` + * To display local variables or parameters just type in + their name: ``localVar``. If you want to inspect variables that are not + in the current stack frame, use the ``up`` or ``down`` command. + + Unfortunately, only inspecting variables is possible at the moment. Maybe + a future version will implement a full-blown Nim expression evaluator, + but this is not easy to do and would bloat the debugger's code. + + Since displaying the whole data structures is often not needed and + painfully slow, the debugger uses a *maximal display depth* concept for + displaying. + + You can alter the maximal display depth with the ``maxdisplay`` + command. + +``maxdisplay`` + Sets the maximal display depth to the given integer value. A value of 0 + means there is no maximal display depth. Default is 3. + +``o``, ``out`` + Evaluate the expression and store its string representation into a + file named . If the file does not exist, it will be created, + otherwise it will be opened for appending. + +``w``, ``where`` + Display the current execution point. + +``u``, ``up`` + Go up in the call stack. + +``d``, ``down`` + Go down in the call stack. + +``stackframe`` [file] + Displays the content of the current stack frame in ``stdout`` or + appends it to the file, depending on whether a file is given. + +``callstack`` + Display the entire call stack (but not its content). + +``l``, ``locals`` + Display the available local variables in the current stack frame. + +``g``, ``globals`` + Display all the global variables that are available for inspection. diff --git a/doc/estp.txt b/doc/estp.txt index 500ee52a5d..805a84eb70 100644 --- a/doc/estp.txt +++ b/doc/estp.txt @@ -1,30 +1,30 @@ -=================================================== - Embedded Stack Trace Profiler (ESTP) User Guide -=================================================== - -:Author: Andreas Rumpf -:Version: |nimversion| - - -Nim comes with a platform independent profiler - -the Embedded Stack Trace Profiler (ESTP). The profiler -is *embedded* into your executable. To activate the profiler you need to do: +=================================================== + Embedded Stack Trace Profiler (ESTP) User Guide +=================================================== -* compile your program with the ``--profiler:on --stackTrace:on`` command +:Author: Andreas Rumpf +:Version: |nimversion| + + +Nim comes with a platform independent profiler - +the Embedded Stack Trace Profiler (ESTP). The profiler +is *embedded* into your executable. To activate the profiler you need to do: + +* compile your program with the ``--profiler:on --stackTrace:on`` command line options * import the ``nimprof`` module * run your program as usual. -You can in fact look at ``nimprof``'s source code to see how to implement +You can in fact look at ``nimprof``'s source code to see how to implement your own profiler. - -The setting ``--profiler:on`` defines the conditional symbol ``profiler``. - -After your program has finished the profiler will create a + +The setting ``--profiler:on`` defines the conditional symbol ``profiler``. + +After your program has finished the profiler will create a file ``profile_results.txt`` containing the profiling results. Since the profiler works by examining stack traces, it's essential that -the option ``--stackTrace:on`` is active! Unfortunately this means that a +the option ``--stackTrace:on`` is active! Unfortunately this means that a profiling build is much slower than a release build. @@ -32,7 +32,7 @@ Memory profiler =============== You can also use ESTP as a memory profiler to see which stack traces allocate -the most memory and thus create the most GC pressure. It may also help to +the most memory and thus create the most GC pressure. It may also help to find memory leaks. To activate the memory profiler you need to do: * compile your program with the ``--profiler:off --stackTrace:on -d:memProfiler`` @@ -40,22 +40,22 @@ find memory leaks. To activate the memory profiler you need to do: * import the ``nimprof`` module * run your program as usual. -Define the symbol ``ignoreAllocationSize`` so that only the number of +Define the symbol ``ignoreAllocationSize`` so that only the number of allocations is counted and the sizes of the memory allocations do not matter. Example results file ==================== -The results file lists stack traces ordered by significance. +The results file lists stack traces ordered by significance. The following example file has been generated by profiling the Nim compiler -itself: It shows that in total 5.4% of the runtime has been spent +itself: It shows that in total 5.4% of the runtime has been spent in ``crcFromRope`` or its children. In general the stack traces show you immediately where the problem is because the trace acts like an explanation; in traditional profilers you can only find -expensive leaf functions easily but the *reason* why they are invoked +expensive leaf functions easily but the *reason* why they are invoked often remains mysterious. :: diff --git a/doc/filters.txt b/doc/filters.txt index e725321e6e..afbd61e3ca 100644 --- a/doc/filters.txt +++ b/doc/filters.txt @@ -4,8 +4,8 @@ Source Code Filters .. contents:: -A `Source Code Filter` transforms the input character stream to an in-memory -output stream before parsing. A filter can be used to provide templating +A `Source Code Filter` transforms the input character stream to an in-memory +output stream before parsing. A filter can be used to provide templating systems or preprocessors. To use a filter for a source file the *shebang* notation is used:: @@ -52,7 +52,7 @@ Parameters and their defaults: ``sub: string = ""`` the substring that is searched for - + ``by: string = ""`` the string the substring is replaced with @@ -71,7 +71,7 @@ Parameters and their defaults: ``leading: bool = true`` strip leading whitespace - + ``trailing: bool = true`` strip trailing whitespace @@ -89,16 +89,16 @@ Parameters and their defaults: ``metaChar: char = '#'`` prefix for a line that contains Nim code - + ``subsChar: char = '$'`` prefix for a Nim expression within a template line - + ``conc: string = " & "`` the operation for concatenation - + ``emit: string = "result.add"`` the operation to emit a string literal - + ``toString: string = "$"`` the operation that is applied to each expression @@ -106,7 +106,7 @@ Example:: #! stdtmpl | standard #proc generateHTMLPage(title, currentTab, content: string, - # tabs: openArray[string]): string = + # tabs: openArray[string]): string = # result = "" $title @@ -114,7 +114,7 @@ Example:: \n" & + " \n" & + "
\n" & + " " & $(content) & "\n" & + " A dollar: $.\n" & + "
\n" & "\n") - + Each line that does not start with the meta character (ignoring leading -whitespace) is converted to a string literal that is added to ``result``. +whitespace) is converted to a string literal that is added to ``result``. The substitution character introduces a Nim expression *e* within the string literal. *e* is converted to a string with the *toString* operation @@ -174,14 +174,14 @@ writes the template code directly to a file:: #! stdtmpl(emit="f.write") | standard #proc writeHTMLPage(f: File, title, currentTab, content: string, - # tabs: openArray[string]) = + # tabs: openArray[string]) = $title