diff --git a/.github/Guidelines/Building.md b/.github/Guidelines/Building.md new file mode 100644 index 00000000..e229691f --- /dev/null +++ b/.github/Guidelines/Building.md @@ -0,0 +1,34 @@ +# Building a Solution + +- Only run `copilotBuild.ps1` to build a solution. +- DO NOT use msbuild by yourself. +- The script builds all projects in a solution. + +## Executing copilotBuild.ps1 + +Before building, ensure the debugger has stopped. +If there is any error message, it means the debugger is not alive, it is good. + +``` +& REPO-ROOT\.github\Scripts\copilotDebug_Stop.ps1 +``` + +And then run this script to build the solution: + +``` +cd SOLUTION-ROOT +& REPO-ROOT\.github\Scripts\copilotBuild.ps1 +``` + +## The Correct Way to Read Compiler Result + +- The only source of trust is the raw output of the compiler. +- Wait for the script to finish before reading the log file. + - DO NOT need to read the output from the script. + - Building takes a long time. DO NOT hurry. + - When the script finishes, the result is saved to `REPO-ROOT/.github/Scripts/Build.log`. + - A temporary file `Build.log.unfinished` is created during building. It will be automatically deleted as soon as the building finishes. If you see this file, it means the building is not finished yet. +- When build succeeds, the last several lines of `Build.log` indicates the number of warnings and errors in the following pattern: + - "Build succeeded." + - "0 Warning(s)" + - "0 Error(s)" diff --git a/.github/Guidelines/Debugging.md b/.github/Guidelines/Debugging.md new file mode 100644 index 00000000..4c52d6a4 --- /dev/null +++ b/.github/Guidelines/Debugging.md @@ -0,0 +1,71 @@ +## Debugging a Project + +Debugging would be useful when you lack necessary information. +In this section I offer you a set of PowerShell scripts that work with CDB (Microsoft's Console Debugger). +CDB accepts the exact same commands as WinDBG. + +### Start a Debugger + +Read `REPO-ROOT/.github/Project.md` to understand the solution folder and the unit test project name you are working with. +Additional information could be found in THE FIRST LINE in `REPO-ROOT/.github/Scripts/Execute.log`. +Execute the following PowerShell commands: + +``` +cd SOLUTION-ROOT +start powershell {& REPO-ROOT\.github\Scripts\copilotDebug_Start.ps1 -Executable PROJECT-NAME} +``` + +The `start powershell {}` is necessary; otherwise the script will block the execution forever causing you to wait infinitely. +The script will finish immediately, leaving a debugger running in the background. You can send commands to the debugger. +The process being debugged is paused at the beginning, you are given a chance to set breakpoints. +After you are prepared, send the `g` command to start running. + +### Stop a Debugger + +You must call this script to stop the debugger. +Do not stop the debugger using any command. +This script is also required to run before compiling only when Visual Studio Code tasks are not available to you. + +``` +& REPO-ROOT\.github\Scripts\copilotDebug_Stop.ps1 +``` + +If there is any error message, it means the debugger is not alive, it is good. + +### Sending Commands to Debugger + +``` +& REPO-ROOT\.github\Scripts\copilotDebug_RunCommand.ps1 -Command "Commands" +``` + +The effect of commands lasts across multiple `copilotDebug_RunCommand.ps1` calls. For example, after you executed `.frame X`, you do not need to repeat it to use `dx` under the same call stack frame in later calls, as `.frame X` is already effective. + +Multiple commands can be executed sequentially separated by ";". +The debugger is configured to be using source mode, which means you can see source files and line numbers in the call stack, and step in/out/over are working line by line. +CDB accepts exactly same commands as WinDBG, and here are some recommended commands: +- **g**: continue until hitting a breakpoint or crashing. +- **k**n: print current call stack. +- **kn LINES**: print first `LINES` of the current call stack. +- **.frame NUMBER**: inspect the call stack frame labeled with `NUMBER`. `kn` will show the number, file and line along with the call stack. +- **dv**: list all available variables in the current call stack frame. +- **dx EXPRESSION**: evaluate the `EXPRESSION` and print the result. `EXPRESSION` can be any valid C programming language expression. When you specify a type (especially when doing casting), full namespaces are required, do not start with `::`. +- **bp `FILE:LINE`**: set a breakpoint at the specified line in `FILE`, starting from 0. A pair of "`" characters are required around the target, this is not a markdown syntax. +- **bl**, **.bpcmds**, **be NUMBERS**, **bd NUMBERS**, **bc NUMBERS**, **bsc NUMBER CONDITION**: list, list with attached commands, enable, disable, delete, attach a command to breakpoint(s). +- **p**: step over, aka execute the complete current line. +- **t**: step in, aka execute the current line, if any function is called, goes into the function. +- **pt**: step out, aka run until the end of the current function. + +An `.natvis` file is automatically offered with the debugger, +it formats some primitive types defined in the `Vlpp` project, +including `WString` and other string types, `Nullable`, `Variant`, container types, etc. +The formatting applies to the **dx** command, +when you want to see raw data instead of formatted printing, +use **dx (EXPRESSION),!**. + +You can also use `dv -rX` to expand "X" levels of fields, the default option is `-r0` which only expands one level of fields. + +### Commands to Avoid + +- Only use **dv** without any parameters. +- DO NOT use **dt**. +- DO NOT use **q**, **qd**, **qq**, **qqd** etc to stop the debugger, always use `copilotDebug_Stop.ps1`. diff --git a/.github/Guidelines/GacUIXmlResource.md b/.github/Guidelines/GacUIXmlResource.md new file mode 100644 index 00000000..67ec7587 --- /dev/null +++ b/.github/Guidelines/GacUIXmlResource.md @@ -0,0 +1,223 @@ +# Syntax of GacUI XML Resources + +- This is a brief introduction for GacUI XML Resource. +- Detailed document can be found in `REPO-ROOT/.github/KnowledgeBase/Index.md` under `# Copy of Online Manual`: + - In `## GacUI`, the `GacUI XML Resource` item and all sub items detailed explain the syntax for GacUI XML Resource. + - In `## Workflow Script`, the `Syntax` item and all sub items detailed explain the syntax for the script language used in GacUI XML Resource. + +## Mapping XML Entity to C++ Entity + +Most XML tags are calling constructors for classes in the following folder: + +- Source\Controls +- Source\Application +- Source\GraphicsCompositions +- Source\GraphicsElement + +All mappings are: + +- presentation::controls::Gui* +- presentation::elements::Gui*Element +- presentation::compositions::Gui*Composition +- presentation::compositions::Gui* +- presentation::templates::Gui* +- system::* +- system::reflection::* +- presentation::* +- presentation::Gui* +- presentation::controls::* +- presentation::controls::list::* +- presentation::controls::tree::* +- presentation::elements::* +- presentation::elements::Gui* +- presentation::elements::text::* +- presentation::compositions::* +- presentation::templates::* +- presentation::theme::* + +When you see `