Merge pull request GaijinEntertainment#2121 from GaijinEntertainment/and-even-more-tutorials

debug agent and apply in context - tutorials and tests, also bugfixes

Author: borisbat

doc/make_pdf.bat

@@ -0,0 +1,39 @@
+@ECHO OFF
+REM Build PDFs using rinohtype (no LaTeX required)
+REM Usage: make_pdf.bat
+
+if "%SPHINXBUILD%" == "" (
+    set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set PDFDIR=%BUILDDIR%\rinoh_pdf
+
+echo Building Reference Manual PDF...
+"D:\Work\daScript\.venv\Scripts\python.exe" -c ^
+    "import sys; sys.setrecursionlimit(10000); ^
+     from sphinx.cmd.build import main; ^
+     main(['-b','rinoh','-d','%BUILDDIR%/doctrees_ref','-D','master_doc=reference/index','source','%PDFDIR%/reference'])"
+if errorlevel 1 (
+    echo ERROR: Reference Manual build failed
+    exit /b 1
+)
+
+echo.
+echo Building Standard Library PDF...
+"D:\Work\daScript\.venv\Scripts\python.exe" -c ^
+    "import sys; sys.setrecursionlimit(10000); ^
+     from sphinx.cmd.build import main; ^
+     main(['-b','rinoh','-d','%BUILDDIR%/doctrees_stdlib','-D','master_doc=stdlib/index','source','%PDFDIR%/stdlib'])"
+if errorlevel 1 (
+    echo ERROR: Standard Library build failed
+    exit /b 1
+)
+
+echo.
+echo Copying PDFs to site/doc...
+if not exist "..\site\doc" mkdir "..\site\doc"
+copy /Y "%PDFDIR%\reference\*.pdf" "..\site\doc\"
+copy /Y "%PDFDIR%\stdlib\*.pdf" "..\site\doc\"
+
+echo.
+echo Done. PDFs are in %PDFDIR% and ..\site\doc\

doc/make_pdf.ps1

@@ -0,0 +1,56 @@
+# Build PDFs using rinohtype (no LaTeX required)
+# Usage: .\make_pdf.ps1
+
+$python = "D:\Work\daScript\.venv\Scripts\python.exe"
+$sphinx = "D:\Work\daScript\.venv\Scripts\sphinx-build.exe"
+$buildDir = "build"
+$pdfDir = "$buildDir\rinoh_pdf"
+$siteDocDir = "..\site\doc"
+
+$buildScript = @"
+import sys
+import threading
+
+def build_main():
+    from sphinx.cmd.build import main
+    raise SystemExit(main(sys.argv[1:]))
+
+sys.setrecursionlimit(10000)
+threading.stack_size(64 * 1024 * 1024)  # 64MB stack
+t = threading.Thread(target=build_main)
+t.start()
+t.join()
+"@
+$buildScriptFile = "$buildDir\sphinx_build_wrapper.py"
+Set-Content -Path $buildScriptFile -Value $buildScript
+
+Write-Host "Building Reference Manual PDF..." -ForegroundColor Cyan
+$env:RINOH_BUILD_MODE = 'reference'
+& $python $buildScriptFile -b rinoh -d "$buildDir/doctrees_ref" `
+    -D "master_doc=reference/index" source "$pdfDir/reference"
+$env:RINOH_BUILD_MODE = ''
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Reference Manual build failed (exit $LASTEXITCODE)"
+    exit 1
+}
+
+Write-Host ""
+Write-Host "Building Standard Library PDF..." -ForegroundColor Cyan
+$env:RINOH_BUILD_MODE = 'stdlib'
+& $python $buildScriptFile -b rinoh -d "$buildDir/doctrees_stdlib" `
+    -D "master_doc=stdlib/index" source "$pdfDir/stdlib"
+$env:RINOH_BUILD_MODE = ''
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Standard Library build failed (exit $LASTEXITCODE)"
+    exit 1
+}
+
+Write-Host ""
+Write-Host "Copying PDFs to $siteDocDir ..." -ForegroundColor Cyan
+if (-not (Test-Path $siteDocDir)) { New-Item -ItemType Directory -Path $siteDocDir | Out-Null }
+Get-ChildItem "$pdfDir\reference", "$pdfDir\stdlib" -Filter "*.pdf" | Copy-Item -Destination $siteDocDir
+
+Write-Host ""
+Write-Host "Done!" -ForegroundColor Green
+Write-Host "PDFs written to: $(Resolve-Path $pdfDir)"
+Write-Host "Copied to site:  $(Resolve-Path $siteDocDir)"

doc/reflections/das2rst.das

@@ -191,6 +191,22 @@ def document_module_network(root : string) {
     document("Network socket library", mod, "network.rst", groups)
 }
 
+def document_module_debugapi(root : string) {
+    var mod = get_module("debugapi")
+    var groups <- array<DocGroup>(
+        group_by_regex("Agent lifecycle", mod, %regex~(fork_debug_agent_context|install_debug_agent|install_debug_agent_thread_local|install_new_debug_agent|install_new_thread_local_debug_agent|has_debug_agent_context|get_debug_agent_context|delete_debug_agent_context|is_in_debug_agent_creation|lock_debug_agent)$%%),
+        group_by_regex("Cross-context invocation", mod, %regex~(invoke_in_context|invoke_debug_agent_method|invoke_debug_agent_function)$%%),
+        group_by_regex("Agent construction", mod, %regex~(make_debug_agent|make_data_walker|make_stack_walker)$%%),
+        group_by_regex("Agent tick and state collection", mod, %regex~(tick_debug_agent|collect_debug_agent_state|on_breakpoints_reset|report_context_state|debug_agent_command|debugger_stop_requested)$%%),
+        group_by_regex("Instrumentation", mod, %regex~(instrument_node|instrument_function|instrument_all_functions|instrument_all_functions_thread_local|instrument_context_allocations|clear_instruments|set_single_step)$%%),
+        group_by_regex("Data and stack walking", mod, %regex~(walk_data|walk_stack|stackwalk|stack_depth)$%%),
+        group_by_regex("Context inspection", mod, %regex~(get_context_global_variable|has_function|get_heap_stats)$%%),
+        group_by_regex("Breakpoints", mod, %regex~(set_hw_breakpoint|clear_hw_breakpoint)$%%),
+        group_by_regex("Memory", mod, %regex~(free_temp_string|temp_string_size|break_on_free|track_insane_pointer)$%%)
+    )
+    document("Debug agent API", mod, "debugapi.rst", groups)
+}
+
 def document_module_uriparser(root : string) {
     var mod = get_module("uriparser")
     var groups <- array<DocGroup>(
@@ -1043,6 +1059,7 @@ def main {
     document_module_fio(root)
     document_module_network(root)
     document_module_uriparser(root)
+    document_module_debugapi(root)
     document_module_rtti(root)
     document_module_ast(root)
     document_module_strings(root)

doc/source/reference/tutorials.rst

@@ -72,6 +72,8 @@ introduced in earlier tutorials.
    tutorials/42_testing_tools.rst
    tutorials/43_interfaces.rst
    tutorials/44_compile_and_run.rst
+   tutorials/45_debug_agents.rst
+   tutorials/46_apply_in_context.rst
 
 .. _tutorials_integration_c:
 

doc/source/reference/tutorials/44_compile_and_run.rst

@@ -281,3 +281,5 @@ Quick reference
    Helper file: :download:`tutorials/language/44_helper.das <../../../../tutorials/language/44_helper.das>`
 
    Previous tutorial: :ref:`tutorial_interfaces`
+
+   Next tutorial: :ref:`tutorial_debug_agents`