mirror of
https://github.com/vczh-libraries/Release.git
synced 2026-09-21 14:13:55 +08:00
Sync Copilot context files
This commit is contained in:
vczh
@@ -6,7 +6,7 @@
|
||||
## Windows Specific
|
||||
|
||||
- Only run `copilotBuild.ps1` to build a solution.
|
||||
- DO NOT use msbuild by yourself.
|
||||
- DO NOT use MSBuild by yourself.
|
||||
- The script builds all projects in a solution.
|
||||
|
||||
### Executing copilotBuild.ps1
|
||||
@@ -19,28 +19,28 @@ cd SOLUTION-ROOT
|
||||
```
|
||||
|
||||
It is possible that, before running `copilotBuild.ps1`, the binary to compile is still running or still being debugged. This could cause the linking to fail. You need to check the error message, and in case when it happens:
|
||||
- Kill `cdb` process first, if there is any.
|
||||
- Kill `cdb` process first, if any.
|
||||
- The cdb path is stored in `$env:CDBPATH`.
|
||||
- Avoid running `copilotDebug_Stop.ps1` directly.
|
||||
- Kill the binary process that is blocked.
|
||||
- Rebuild, and this issue should gone.
|
||||
- Rebuild, and this issue should be gone.
|
||||
|
||||
### Ensure Target Configuration
|
||||
|
||||
`-Configuration` and `-Platform` arguments are available to specify the target configuration:
|
||||
- `-Configuration` could be `Debug` (default) or `Release`.
|
||||
- `-Platform` could be `x64` (default) or `Win32`
|
||||
- Pick the default option (omit both arguments) when there is no specific requirements.
|
||||
- `-Configuration` can be `Debug` (default) or `Release`.
|
||||
- `-Platform` can be `x64` (default) or `Win32`
|
||||
- Pick the default option (omit both arguments) when there is no specific requirement.
|
||||
|
||||
### The Correct Way to Read Compiler Result
|
||||
|
||||
- The only source of trust is the raw output of the compiler.
|
||||
- The only source of truth 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:
|
||||
- When build succeeds, the last several lines of `Build.log` indicate the number of warnings and errors in the following pattern:
|
||||
- "Build succeeded."
|
||||
- "0 Warning(s)"
|
||||
- "0 Error(s)"
|
||||
@@ -48,15 +48,15 @@ It is possible that, before running `copilotBuild.ps1`, the binary to compile is
|
||||
|
||||
## Linux Specific
|
||||
|
||||
Building only happens on a folder that has a `vmake` file.
|
||||
Building only happens in a folder that has a `vmake` file.
|
||||
- If the repo has only one project, it is in `REPO-ROOT/Test/Linux`.
|
||||
- If the repo has multiple projects, it is in `REPO-ROOT/Test/Linux/PROJECT-NAME`.
|
||||
- `PROJECT-NAME` naming is following `PROJECT-NAME.vcxproj`.
|
||||
- The `PROJECT-NAME` name follows `PROJECT-NAME.vcxproj`.
|
||||
You are required to `cd` to such folder before running `build.sh`, otherwise it will fail.
|
||||
|
||||
Call `REPO-ROOT/.github/Ubuntu/build.sh` for incremental build.
|
||||
Call `REPO-ROOT/.github/Ubuntu/build.sh -f` for full rebuild.
|
||||
`build.sh` will read the local `vmake` configuration file and generate a `makefile` in the same folder before building.
|
||||
`build.sh` will also run other script files in that folder, run `chmod +x` if any script file is blocked.
|
||||
`build.sh` will also run other script files in that folder; you may need to run `chmod +x` if any script file is blocked.
|
||||
|
||||
Only the "debug x64" configuration is supported on Linux. If you are instructed to build and run other configuration, ignore it.
|
||||
|
||||
@@ -5,14 +5,14 @@
|
||||
|
||||
## Windows Specific
|
||||
|
||||
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.
|
||||
Debugging can be useful when you lack necessary information.
|
||||
This section offers a set of PowerShell scripts that work with CDB (Microsoft's Console Debugger).
|
||||
CDB accepts exactly the same commands as WinDBG.
|
||||
|
||||
### Start a Debugger
|
||||
|
||||
Read `REPO-ROOT/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`.
|
||||
Additional information can be found in the first line of `REPO-ROOT/.github/Scripts/Execute.log`.
|
||||
Execute the following PowerShell commands:
|
||||
|
||||
```
|
||||
@@ -22,10 +22,10 @@ start powershell {& REPO-ROOT\.github\Scripts\copilotDebug_Start.ps1 -Executable
|
||||
|
||||
If the debugger is already started, this script will fail because the pipe name is occupied. That probably means the last time you forgot to stop the debugger. You can kill `cdb` and the process being debugged, before starting a new debugger.
|
||||
|
||||
The `start powershell {}` is necessary; otherwise the script will block the execution forever causing you to wait infinitely.
|
||||
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.
|
||||
The process being debugged is paused at the beginning; you are given a chance to set breakpoints.
|
||||
After you are ready, send the `g` command to start running.
|
||||
|
||||
### Stop a Debugger
|
||||
|
||||
@@ -37,15 +37,15 @@ This script is also required to run before compiling only when Visual Studio Cod
|
||||
& REPO-ROOT\.github\Scripts\copilotDebug_Stop.ps1
|
||||
```
|
||||
|
||||
If there is any error message, it means the debugger is not alive, it is good.
|
||||
If there is any error message, it means the debugger is not alive, which is fine.
|
||||
|
||||
#### Warning
|
||||
|
||||
You should never combine `copilotDebug_Stop.ps1` with others in one single powershell call.
|
||||
It could block you forever if some system thing went wrong.
|
||||
You should never combine `copilotDebug_Stop.ps1` with others in one single PowerShell call.
|
||||
It could block you forever if some system issue occurs.
|
||||
You should run this script separately, and do not just wait for its input.
|
||||
The script is supposed to be done very fast, you should keep reading the terminal output parallelly.
|
||||
And when it seems to never finish, kill the terminal and cdb directly.
|
||||
The script is supposed to be done very fast, so you should keep reading the terminal output in parallel.
|
||||
When it seems to never finish, kill the terminal and cdb directly.
|
||||
|
||||
### Sending Commands to Debugger
|
||||
|
||||
@@ -53,44 +53,44 @@ And when it seems to never finish, kill the terminal and cdb directly.
|
||||
& 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.
|
||||
The effect of commands lasts across multiple `copilotDebug_RunCommand.ps1` calls. For example, after you execute `.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:
|
||||
Multiple commands can be executed in sequence, separated by ";".
|
||||
The debugger is configured to use source mode, which means you can see source files and line numbers in the call stack, and step in/out/over work line by line.
|
||||
CDB accepts exactly the 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.
|
||||
- **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 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,
|
||||
An `.natvis` file is automatically provided 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.
|
||||
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`.
|
||||
- DO NOT use **q**, **qd**, **qq**, **qqd** etc. to stop the debugger; always use `copilotDebug_Stop.ps1`.
|
||||
|
||||
## Linux Specific
|
||||
|
||||
Like building and running, debugging must be performed from the same folder that contains `vmake`:
|
||||
- If the repo has only one project, it is in `REPO-ROOT/Test/Linux`.
|
||||
- If the repo has multiple projects, it is in `REPO-ROOT/Test/Linux/PROJECT-NAME`.
|
||||
- `PROJECT-NAME` naming is following `PROJECT-NAME.vcxproj`.
|
||||
- The `PROJECT-NAME` name follows `PROJECT-NAME.vcxproj`.
|
||||
You are required to `cd` to such folder before launching `lldb`, otherwise relative paths to the binary and source files will be wrong.
|
||||
|
||||
`lldb` is going to block the terminal and wait for interaction, you should always start `lldb` in a PTY-backed tool session, for example:
|
||||
@@ -99,7 +99,7 @@ You are required to `cd` to such folder before launching `lldb`, otherwise relat
|
||||
lldb -- ./Bin/UnitTest /C
|
||||
```
|
||||
|
||||
Keep the session id returned by the tool. Send debugger commands as newline-terminated stdin, one round at a time, and wait for output between rounds.
|
||||
Keep the session ID returned by the tool. Send debugger commands as newline-terminated stdin, one round at a time, and wait for output between rounds.
|
||||
|
||||
End the session with:
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
# Syntax of GacUI XML Resources
|
||||
|
||||
- This is a brief introduction for GacUI XML Resource.
|
||||
- This is a brief introduction to 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.
|
||||
- In `## GacUI`, the `GacUI XML Resource` item and all subitems explain the syntax for GacUI XML Resource in detail.
|
||||
- In `## Workflow Script`, the `Syntax` item and all subitems explain the syntax for the script language used in GacUI XML Resource in detail.
|
||||
|
||||
## Mapping XML Entity to C++ Entity
|
||||
|
||||
Most XML tags are calling constructors for classes in the following folder:
|
||||
Most XML tags call constructors for classes in the following folders:
|
||||
|
||||
- Source\Controls
|
||||
- Source\Application
|
||||
@@ -36,14 +36,14 @@ All mappings are:
|
||||
- presentation::theme::*
|
||||
|
||||
When you see `<Button>`,
|
||||
try all mappings and for example `presentation::elements::Gui*`,
|
||||
replacing `*` with the tag and you will get `presentation::elements::GuiButton`,
|
||||
try all mappings and for example `presentation::elements::Gui*`;
|
||||
replacing `*` with the tag gives you `presentation::elements::GuiButton`,
|
||||
it is an existing C++ class!
|
||||
So `<Button>` means `presentation::controls::GuiButton`.
|
||||
Following the same rule, `<Table>` would be `presentation::compositions::GuiTableComposition` and `<SolidLabel>` would be `presentation::elements::GuiSolidLabelElement`.
|
||||
|
||||
Take this file `Test\Resources\Metadata\Reflection64.txt` as an index, it collects all valid C++ classes and their members, but written in my own format.
|
||||
When there is a `@FullName` on top of a class, it means the full name in C++, the class name will be the full name in XML.
|
||||
When there is a `@FullName` on top of a class, it means the full name in C++; the class name will be the full name in XML.
|
||||
When there is no `@FullName` but the class name begins with `presentation::`, the full name in C++ begins with `vl::presentation::`.
|
||||
|
||||
## XML in a Single String
|
||||
@@ -139,7 +139,7 @@ To expand a composition to the whole parent client area:
|
||||
The most useful composition is `<Table>`, it is a grid layout with rows and columns. There are 3 sizing modes for rows and columns:
|
||||
- `<_>composeType:MinSize</_>`: The size is decided by its content.
|
||||
- `<_>composeType:Absolute absolute:10</_>`: The size is 10.
|
||||
- `<_>composeType:Percentage percentage:0.5</_>`: The size is 50% of all space excludes MinSizes and Absolutes.
|
||||
- `<_>composeType:Percentage percentage:0.5</_>`: The size is 50% of all space excluding MinSizes and Absolutes.
|
||||
|
||||
The `CellPadding` property defines the space between cells, default 0. The `BorderVisible` adds `CellPadding` around the border, default true. Obviously the following two tables are identical.
|
||||
```XML
|
||||
@@ -147,21 +147,21 @@ The `CellPadding` property defines the space between cells, default 0. The `Bord
|
||||
<Table AlignmentToParent="left:3 top:3 right:3 bottom:3" CellPadding="5" BorderVisible="true"/>
|
||||
```
|
||||
|
||||
In order to make a table expanded to the whole window and placing a button at the center:
|
||||
In order to make a table expand to the whole window and place a button at the center:
|
||||
- Set rows to Percentage 0.5; MinSize; Percentage 0.5
|
||||
- Set columns to Percentage 0.5; MinSize; Percentage 0.5
|
||||
- Put the button to the center cell, which is `Site="row:1 column:1"`
|
||||
- Put the button in the center cell, which is `Site="row:1 column:1"`
|
||||
|
||||
We can also list 3 buttons vertically in the top-left corner of the window:
|
||||
- Set rows to MinSize; MinSize; MinSize; Percentage 1.0
|
||||
- Set columns to MinSize; Percentage 1.0
|
||||
- Put 3 button to all MinSize cells, which is `Site="row:0 column:0"`, `Site="row:1 column:0"`, `Site="row:2 column:0"`
|
||||
- Put 3 buttons in all MinSize cells, which is `Site="row:0 column:0"`, `Site="row:1 column:0"`, `Site="row:2 column:0"`
|
||||
|
||||
To make a dialog with big content with OK and Cancel buttons at the bottom-right corner:
|
||||
- Set rows to Percentage 1.0; MinSize
|
||||
- Set columns to Percentage 1.0; MinSize; MinSize
|
||||
- Put the content to the cell that automatically expands to the rest of the space, which is `Site="row:0 column:0"`
|
||||
- Put 2 button to all MinSize cells, which is `Site="row:1 column:1"`, `Site="row:1 column:2"`
|
||||
- Put the content in the cell that automatically expands to the rest of the space, which is `Site="row:0 column:0"`
|
||||
- Put 2 buttons in all MinSize cells, which is `Site="row:1 column:1"`, `Site="row:1 column:2"`
|
||||
|
||||
### Others
|
||||
|
||||
@@ -204,7 +204,7 @@ To access properties in the nested level, the `-set` binding is required:
|
||||
|
||||
This example changes the property `AlignmentToParent` to the object in label's `BoundsComposition` property.
|
||||
|
||||
If a property name looks like `Name-binding`, it means the property `Name` should interpret the content using the specified way `-binding`. There are more predefined bindings like `-ref`, `-uri`, `-eval`, `-bind`, etc.
|
||||
If a property name looks like `Name-binding`, it means the property `Name` should interpret the content using the specified binding `-binding`. There are more predefined bindings like `-ref`, `-uri`, `-eval`, `-bind`, etc.
|
||||
|
||||
## Events
|
||||
|
||||
@@ -218,6 +218,6 @@ An event is subscribed like:
|
||||
</Button>
|
||||
```
|
||||
|
||||
It means when button's `Clicked` event happens, execute some code.
|
||||
It means when the button's `Clicked` event happens, execute some code.
|
||||
|
||||
Code in an event of in the `<Workflow>` resource item should be Workflow Script instead of C++.
|
||||
Code in an event or in the `<Workflow>` resource item should be Workflow Script instead of C++.
|
||||
|
||||
@@ -5,41 +5,42 @@
|
||||
|
||||
## Windows Specific
|
||||
|
||||
- Only run `copilotExecute.ps1` to run a unit test project.
|
||||
- Only run `copilotExecute.ps1` to run a CLI application project.
|
||||
- DO NOT call executables or scripts yourself.
|
||||
|
||||
### Executing copilotExecute.ps1
|
||||
|
||||
`PROJECT-NAME` is the name of the project.
|
||||
Run test cases in `SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj`:
|
||||
Run the CLI application built from `SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj`:
|
||||
|
||||
```
|
||||
cd SOLUTION-ROOT
|
||||
& REPO-ROOT\.github\Scripts\copilotExecute.ps1 -Mode UnitTest -Executable PROJECT-NAME
|
||||
& REPO-ROOT\.github\Scripts\copilotExecute.ps1 -Mode CLI -Executable PROJECT-NAME
|
||||
```
|
||||
|
||||
`-Mode` and `-Executable` are required.
|
||||
|
||||
`-Configuration` and `-Platform` arguments are available to specify the target configuration:
|
||||
- When both arguments are omitted, the last build configuration will be picked up.
|
||||
- Both arguments should be omitted or not omitted at the same time.
|
||||
- `-Configuration` could be `Debug` (default) or `Release`.
|
||||
- `-Platform` could be `x64` (default) or `Win32`
|
||||
- Pick the default option (omit both arguments) when there is no specific requirements.
|
||||
- Both arguments should be provided together or omitted together.
|
||||
- `-Configuration` can be `Debug` (default) or `Release`.
|
||||
- `-Platform` can be `x64` (default) or `Win32`
|
||||
- Pick the default option (omit both arguments) when there is no specific requirement.
|
||||
|
||||
## Linux Specific
|
||||
|
||||
Building only happens on a folder that has a `vmake` file.
|
||||
Building only happens in a folder that has a `vmake` file.
|
||||
- If the repo has only one project, it is in `REPO-ROOT/Test/Linux`.
|
||||
- If the repo has multiple projects, it is in `REPO-ROOT/Test/Linux/PROJECT-NAME`.
|
||||
- `PROJECT-NAME` naming is following `PROJECT-NAME.vcxproj`.
|
||||
- The `PROJECT-NAME` name follows `PROJECT-NAME.vcxproj`.
|
||||
You are required to `cd` to such folder before running the compiled CLI binary, otherwise it will fail.
|
||||
|
||||
After a successful build, `Bin/UnitTest` will be generated as the executable.
|
||||
If you can'f find it, first check if the build succeeded, and then read `makefile` to find the correct binary file name.
|
||||
If you can't find it, first check if the build succeeded, and then read `makefile` to find the correct binary file name.
|
||||
`Bin/UnitTest` is the default name in any `vmake` if it is not changed, so many CLI application still named `UnitTest`.
|
||||
|
||||
**IMPORTANT**: Always run it async, read terminal output and its return code.
|
||||
Compiled binary might have bug causing it to trap in a dead looping. DO NOT just wait for it to complete.
|
||||
If you feel suspicious, you are recommended to kill the process and run it again with the debugger.
|
||||
**IMPORTANT**: Always run it asynchronously, read terminal output and its return code.
|
||||
Compiled binary might have a bug causing it to trap in a dead loop. DO NOT just wait for it to complete.
|
||||
If this seems suspicious, you are recommended to kill the process and run it again with the debugger.
|
||||
|
||||
Only the "debug x64" configuration is supported on Linux. If you are instructed to build and run other configuration, ignore it.
|
||||
|
||||
@@ -22,72 +22,72 @@ cd SOLUTION-ROOT
|
||||
|
||||
`-Configuration` and `-Platform` arguments are available to specify the target configuration:
|
||||
- When both arguments are omitted, the last build configuration will be picked up.
|
||||
- Both arguments should be omitted or not omitted at the same time.
|
||||
- `-Configuration` could be `Debug` (default) or `Release`.
|
||||
- `-Platform` could be `x64` (default) or `Win32`
|
||||
- Pick the default option (omit both arguments) when there is no specific requirements.
|
||||
- Both arguments should be provided together or omitted together.
|
||||
- `-Configuration` can be `Debug` (default) or `Release`.
|
||||
- `-Platform` can be `x64` (default) or `Win32`
|
||||
- Pick the default option (omit both arguments) when there is no specific requirement.
|
||||
|
||||
### Ensure Expected Test Files are Selected
|
||||
|
||||
Test cases are organized in multiple test files.
|
||||
In `PROJECT-NAME\PROJECT-NAME.vcxproj.user` there is a filter, when it is effective, you will see filtered test files marked with `[SKIPPED]` in `Execute.log`.
|
||||
In `PROJECT-NAME\PROJECT-NAME.vcxproj.user` there is a filter. When it is effective, you will see filtered test files marked with `[SKIPPED]` in `Execute.log`.
|
||||
The filter is defined in this XPath: `/Project/PropertyGroup@Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"/LocalDebuggerCommandArguments`.
|
||||
The filter is effective only when the file exists and the element exists with one or multiple `/F:FILE-NAME.cpp`, listing all test files to execute, unlisted files are skipped.
|
||||
If the element exists but there is no `/F:FILE-NAME.cpp`, it executes all test files, none is skipped.
|
||||
|
||||
**IMPORTANT**:
|
||||
|
||||
ONLY WHEN test files you want to run is skipped, you can edit `PROJECT-NAME\PROJECT-NAME.vcxproj.user` to activate your filter.
|
||||
ONLY WHEN test files you want to run are skipped, you can edit `PROJECT-NAME\PROJECT-NAME.vcxproj.user` to activate your filter.
|
||||
- This would typically happen when:
|
||||
- A new test file is added.
|
||||
- A test file is renamed.
|
||||
|
||||
You can clean up the filter to remove unrelated files that are either not existing or are totally unrelated to the current task you are working on.
|
||||
If the current task does not work on that test file, but it tests a closely related topic, you should better keep it in the list.
|
||||
You can clean up the filter to remove files that are either nonexistent or totally unrelated to the current task you are working on.
|
||||
If the current task does not work on that test file, but it tests a closely related topic, you should keep it in the list.
|
||||
|
||||
DO NOT delete this `*.vcxproj.user` file.
|
||||
DO NOT clean the filter (aka delete all `/FILE-NAME.cpp`) by yourself. I put a filter there because running everything is slow and unnecessary for the current task.
|
||||
DO NOT clean the filter (aka delete all `/F:FILE-NAME.cpp`) by yourself. I put a filter there because running everything is slow and unnecessary for the current task.
|
||||
Ignore `LocalDebuggerCommandArgumentsHistory` in `*.vcxproj.user`.
|
||||
|
||||
### The Correct Way to Read Test Result
|
||||
|
||||
- The only source of trust is the raw output of the unit test process.
|
||||
- The only source of truth is the raw output of the unit test process.
|
||||
- Wait for the script to finish before reading the log file.
|
||||
- DO NOT need to read the output from the script.
|
||||
- Testing takes a long time. DO NOT hurry.
|
||||
- When the script finishes, the result is saved to `REPO-ROOT/.github/Scripts/Execute.log`.
|
||||
- A temporary file `Execute.log.unfinished` is created during testing. It will be automatically deleted as soon as the testing finishes. If you see this file, it means the testing is not finished yet.
|
||||
- Read `Execute.log.unfinished` every 5 minutes.
|
||||
- If the log is not updated, it is possible that the unit test raised a fatal error and blocked by the system message dialog. You need to:
|
||||
- If the log is not updated, it is possible that the unit test raised a fatal error and is blocked by a system message dialog. You need to:
|
||||
- Kill the unit test process.
|
||||
- You are required to run the unit test with debugger attached. The fatal error will report to the debugger and you can see what happened.
|
||||
- When all test cases pass, the last several lines of `Execute.log` should be in the following pattern; otherwise it crashed at the last shown test case:
|
||||
- You are required to run the unit test with the debugger attached. The fatal error will be reported to the debugger and you can see what happened.
|
||||
- When all test cases pass, the last several lines of `Execute.log` should be in the following pattern; otherwise it has crashed at the last shown test case:
|
||||
- "Passed test files: X/X"
|
||||
- "Passed test cases: Y/Y"
|
||||
- DO NOT delete the log file by yourself.
|
||||
|
||||
## Linux Specific
|
||||
|
||||
Building only happens on a folder that has a `vmake` file.
|
||||
Building only happens in a folder that has a `vmake` file.
|
||||
- If the repo has only one project, it is in `REPO-ROOT/Test/Linux`.
|
||||
- If the repo has multiple projects, it is in `REPO-ROOT/Test/Linux/PROJECT-NAME`.
|
||||
- `PROJECT-NAME` naming is following `PROJECT-NAME.vcxproj`.
|
||||
- The `PROJECT-NAME` name follows `PROJECT-NAME.vcxproj`.
|
||||
You are required to `cd` to such folder before running the compiled unit test binary, otherwise it will fail.
|
||||
|
||||
After a successful build, `Bin/UnitTest` will be generated as the executable.
|
||||
If you can'f find it, first check if the build succeeded, and then read `makefile` to find the correct binary file name.
|
||||
The unit test project supports following command line options:
|
||||
If you can't find it, first check if the build succeeded, and then read `makefile` to find the correct binary file name.
|
||||
The unit test project supports the following command line options:
|
||||
- `/D`: crash at the first failure, the error message is not printed. This is recommended for debugging.
|
||||
- `/C`: crash at the first failure and print the error message if possible. This is recommended for usual running.
|
||||
- `/R`: print all failures without crashing. Be careful to use it because failure cases usually affect following cases, making everything not stable after the first failure.
|
||||
- `/R`: print all failures without crashing. Be careful when using it because failure cases usually affect subsequent cases, making everything unstable after the first failure.
|
||||
- `/F:FILENAME.cpp`: file filter.
|
||||
- If no `/F` appears, all test cpp files will run.
|
||||
- If one or multiple `/F` appear, only specified cpp files will run.
|
||||
- `FILENAME.cpp` do not contain file path, and it is case sensitive.
|
||||
- `FILENAME.cpp` does not contain a file path, and it is case sensitive.
|
||||
|
||||
**IMPORTANT**: Always run it async, read terminal output and its return code.
|
||||
Compiled binary might have bug causing it to trap in a dead looping. DO NOT just wait for it to complete.
|
||||
If you feel suspicious, you are recommended to kill the process and run it again with the debugger.
|
||||
When `/D` or `/C` is specified, the unit test binary stops at the first failure, causing it not able to summary how many test cases pass or fail at the end. This would be an obvious signal to tell that it fails.
|
||||
**IMPORTANT**: Always run it asynchronously, read terminal output and its return code.
|
||||
Compiled binary might have a bug causing it to trap in a dead loop. DO NOT just wait for it to complete.
|
||||
If this seems suspicious, you are recommended to kill the process and run it again with the debugger.
|
||||
When `/D` or `/C` is specified, the unit test binary stops at the first failure, causing it to be unable to summarize how many test cases pass or fail at the end. This is an obvious signal that it fails.
|
||||
|
||||
Only the "debug x64" configuration is supported on Linux. If you are instructed to build and run other configuration, ignore it.
|
||||
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
- A solution file (`*.sln` or `*.slnx`) contains multiple project files.
|
||||
- Typical C++ project files are XML files in `*.vcxproj` or `*.vcxitems` naming.
|
||||
- The XML file `*.vcxitems.filters` or `*.vcxproj.filters` organizes source files in solution explorer folders (virtual folders) that could be different from physical file system, which creates a human friendly view.
|
||||
- The XML file `*.vcxitems.filters` or `*.vcxproj.filters` organizes source files in solution explorer folders (virtual folders) that can be different from the physical file system, creating a human-friendly view.
|
||||
- The XML file `*.vcxproj.user` contains some temporary local configuration for a project. This file is not tracked by git, but it contains arguments for running the project.
|
||||
- When adding a source file to a specific solution explorer folder:
|
||||
- It must be also added to one or multiple project files.
|
||||
- It must also be added to one or multiple project files.
|
||||
- Find the `*.vcxitems.filters` or `*.vcxproj.filters` file with the same name.
|
||||
- Each file must be attached to a solution explorer folder, described in this XPath: `/Project/ItemGroup/ClCompile@Include="PhysicalFile"/Filter`.
|
||||
- Inside the `Filter` tag there is the solution explorer folder.
|
||||
@@ -17,13 +17,13 @@
|
||||
|
||||
## Working on Linux
|
||||
|
||||
`makefile` for each project is generated from MSBuild project files during building.
|
||||
`makefile` for each project is generated from MSBuild project files during the build.
|
||||
When the file list needs to be modified, update MSBuild project files directly.
|
||||
After building, `vmake` file generates both `vmake.txt` and `makefile`.
|
||||
If you doubt if the file is built or not, check out `vmake.txt`, which simply lists all used `cpp` files in `makefile`.
|
||||
If you doubt whether the file is built or not, check out `vmake.txt`, which simply lists all used `cpp` files in `makefile`.
|
||||
|
||||
Linux specific C++ source files also need to add to MSBuild project files, and they are excluded from the build.
|
||||
In `vmake`, Windows specific C++ sourve files need to be excluced.
|
||||
Linux specific C++ source files also need to be added to MSBuild project files, and they are excluded from the build.
|
||||
In `vmake`, Windows specific C++ source files need to be excluded.
|
||||
When the `Main.cpp` from MSBuild projects or similar files does not work on Linux, you are recommended to create one for Linux.
|
||||
|
||||
In `vmake`, these variables are available for configuration, most of them are optional:
|
||||
@@ -31,5 +31,5 @@ In `vmake`, these variables are available for configuration, most of them are op
|
||||
- `CPP_REMOVES`: Files to exclude, from the file list generated from `CPP_VCXPROJS`.
|
||||
- `CPP_ADDS`: Files to add.
|
||||
- `CPP_COMPILE_OPTIONS`: Extra compiler options for `clang++` or `g++`.
|
||||
- `FOLDERS`: Folders that containing generated files, these folders will be completely removed during full build.
|
||||
- `FOLDERS`: Folders that contain generated files. These folders will be completely removed during a full build.
|
||||
- `CPP_TARGET`: The compiled binary.
|
||||
|
||||
Reference in New Issue
Block a user