Mirrors_UI_SDK/GacUI
1
0
Fork 0
mirror of https://github.com/vczh-libraries/Release.git synced 2026-03-23 15:52:56 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update prompts

Browse Source
This commit is contained in:
vczh
2026-02-05 15:53:47 -08:00
parent b9ee2b3e22
commit fe2a56d5bf
40 changed files with 1125 additions and 1793 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
.github/Guidelines/Building.md vendored Normal file
View File

@@ -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)"

71
.github/Guidelines/Debugging.md vendored Normal file
View File

@@ -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`.

223
.github/Guidelines/GacUIXmlResource.md vendored Normal file
View File

@@ -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 `<Button>`,
try all mappings and for example `presentation::elements::Gui*`,
replacing `*` with the tag and you will get `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 no `@FullName` but the class name begins with `presentation::`, the full name in C++ begins with `vl::presentation::`.
## XML in a Single String
To define an empty window, the XML looks like:
```xml
<Resource>
<Instance name="MainWindowResource">
<Instance ref.Class="gacuisrc_unittest::MainWindow">
<Window ref.Name="self" Text="GuiRibbonGallery" ClientSize="x:480 y:320">
</Window>
</Instance>
</Instance>
</Resource>
```
The first `<Instance>` defines the resource named `MainWindowResource`, the `<Instance>` inside is the content. You can also add a script like this:
```xml
<Resource>
<Instance name="MainWindowResource">
<Instance ref.Class="gacuisrc_unittest::MainWindow">
<Window ref.Name="self" Text="GuiRibbonGallery" ClientSize="x:480 y:320">
<Label Text="This is a demo"/>
</Window>
</Instance>
</Instance>
<Folder name="Scripts">
<Script name="ViewModelResource">
<Workflow>
<![CDATA[
module viewmodel;
using system::*;
using presentation::*;
namespace demo
{
enum MyCategory
{
Black = 0,
Red = 1,
Lime = 2,
Blue = 3,
White = 4,
}
func ToString(value : DateTime) : string
{
return $"$(value.month)/$(value.day)/$(value.year)";
}
}
]]>
</Workflow>
</Script>
</Folder>
</Resource>
```
One more `Scripts\ViewModelResource` is added to the resource, and the content of the new resource is defined by `<Workflow>`. Code inside `<Workflow>` will always be Workflow Script instead of C++.
## UI Layout
This is the GacUI XML document for UI layout: https://gaclib.net/doc/current/gacui/components/compositions/home.html
To expand a composition to the whole parent client area:
```XML
<AnyComposition AlignmentToParent="left:0 top:0 right:0 bottom:0"/>
```
- `MinSizeLimitation="LimitToElementAndChildren"` for a composition limits its minimum size to the sum of all its children.
- `AlignmentToParent="left:8 top:8 right:8 bottom:8"` for a composition sticks itself to the parent's whole client area with 8 pixels on each side. If the number is -1, it means it doesn't stick to the specific parent's client area side. When both `left` and `right` are -1, it sticks to the left. When both `top` and `bottom` are -1, it sticks to the top. The default value is all -1.
`BoundsComposition` of a control is its boundary composition. To expand a control to the whole parent client area:
```XML
<AnyControl>
<att.BoundsComposition-set AlignmentToParent="left:0 top:0 right:0 bottom:0"/>
</AnyControl>
```
`<Cell>`, `<RowSplitter>`, `<ColumnSplitter>`, `<StackItem>` and `<FlowItem>` are controlled by its parent composition, no positions or size limits need to be adjusted.
### Bounds
`<Bounds>` is useful to define a space.
### Table
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.
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
<Table AlignmentToParent="left:8 top:8 right:8 bottom:8" CellPadding="5" BorderVisible="false"/>
<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:
- 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"`
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"`
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"`
### Others
Please read the document of GacUI XML for other compositions: https://gaclib.net/doc/current/gacui/components/compositions/home.html
- Stack/StackItem
- Flow/FlowItem
- SharedSizeRoot/SharedSizeItem
- SideAligned
- PartialView
- etc
## Properties
There are two ways to add a property:
```xml
<Label Text="This is a demo"/>
```
```xml
<Label>
<att.Text>This is a demo</att.Text>
</Label>
```
If the object assigned to a property cannot be written as a string, the second way is the only way to do that, for example:
```xml
<Label>
</Label>
```
To access properties in the nested level, the `-set` binding is required:
```xml
<Label>
<att.BoundsComposition-set AlignmentToParent="left:0 top:0 right:0 bottom:0"/>
</Label>
```
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.
## Events
An event is subscribed like:
```xml
<Button>
<ev.Clicked-eval><![CDATA[{
// some code
}]]></ev.Clicked-eval>
</Button>
```
It means when 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++.

3
.github/Guidelines/Running-CLI.md vendored Normal file
View File

@@ -0,0 +1,3 @@
# Running a CLI Application Project
(to edit ...)

3
.github/Guidelines/Running-GacUI.md vendored Normal file
View File

@@ -0,0 +1,3 @@
# Running a GacUI Application Project
(to edit ...)

56
.github/Guidelines/Running-UnitTest.md vendored Normal file
View File

@@ -0,0 +1,56 @@
# Running a Unit Test Project
- Only run `copilotExecute.ps1` to run a unit test project.
- DO NOT call executables or scripts yourself.
## Executing copilotExecute.ps1
`PROJECT-NAME` is the name of the project.
Before testing, 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 test cases in `SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj`:
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\Scripts\copilotExecute.ps1 -Executable PROJECT-NAME
```
## 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`.
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.
- 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.
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.
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.
- 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.
- 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:
- "Passed test files: X/X"
- "Passed test cases: Y/Y"

16
.github/Guidelines/SourceFileManagement.md vendored Normal file
View File

@@ -0,0 +1,16 @@
# Solution and Project File Structure
- 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 `*.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.
- 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.
- Edit that `*.vcxitems.filters` or `*.vcxproj.filters` file to include the source file.
## Renaming and Removing Source Files
- All affected `*.vcxitems`, `*.vcxproj`, `*.vcxitems.filters` and `*.vcxproj.filters` must be updated.

56
.github/KnowledgeBase/KnowledgeBase.vcxitems vendored
View File

@@ -1,56 +0,0 @@
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup Label="Globals">
<MSBuildAllProjects Condition="'$(MSBuildVersion)' == '' Or '$(MSBuildVersion)' &lt; '16.0'">$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
<HasSharedItems>true</HasSharedItems>
<ItemsProjectGuid>{D178E490-7C2B-43FA-A8B3-A3BED748EB38}</ItemsProjectGuid>
</PropertyGroup>
<ItemDefinitionGroup>
<ClCompile>
<AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);$(MSBuildThisFileDirectory)</AdditionalIncludeDirectories>
</ClCompile>
</ItemDefinitionGroup>
<ItemGroup>
<ProjectCapability Include="SourceItemsFromImports" />
</ItemGroup>
<ItemGroup>
<None Include="$(MSBuildThisFileDirectory)Index.md" />
<None Include="$(MSBuildThisFileDirectory)Learning.md" />
<None Include="$(MSBuildThisFileDirectory)KB_GacUI_Design_AddingNewControl.md" />
<None Include="$(MSBuildThisFileDirectory)KB_GacUI_Design_ControlFocusSwitchingAndTabAltHandling.md" />
<None Include="$(MSBuildThisFileDirectory)KB_GacUI_Design_ImplementingIGuiGraphicsElement.md" />
<None Include="$(MSBuildThisFileDirectory)KB_GacUI_Design_LayoutAndGuiGraphicsComposition.md" />
<None Include="$(MSBuildThisFileDirectory)KB_GacUI_Design_ListControlArchitecture.md" />
<None Include="$(MSBuildThisFileDirectory)KB_GacUI_Design_MainWindowModalWindow.md" />
<None Include="$(MSBuildThisFileDirectory)KB_GacUI_Design_PlatformInitialization.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_AdditionalStreams.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_EncodingDecoding.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_FileSystemOperations.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_LocaleSupport.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_MultiThreading.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_StreamOperations.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_SynchronizationPrimitives.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppOS_WaitableObjects.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppReflection_ClassInterfaceRegistration.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppReflection_CompilationLevels.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppReflection_EnumRegistration.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppReflection_InterfaceProxy.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppReflection_StructRegistration.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppReflection_TypeMetadata.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppReflection_TypeRegistrationStructure.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppRegex_PatternMatching.md" />
<None Include="$(MSBuildThisFileDirectory)KB_VlppRegex_TypeAliases.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_CollectionTypes.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_ConsoleOperations.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_DateTimeOperations.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_Design_ImplementingInjectableFeature.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_ExceptionHandling.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_LambdaExpressions.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_LinqOperations.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_MemoryLeakDetection.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_ObjectModel.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_PrimitiveTypes.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_SortingOrdering.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_StringTypes.md" />
<None Include="$(MSBuildThisFileDirectory)KB_Vlpp_UnitTesting.md" />
</ItemGroup>
</Project>

4
.github/Project.md vendored Normal file
View File

@@ -0,0 +1,4 @@
# Projects to Work on
You are working on the solution `REPO-ROOT\Test\UnitTest\UnitTest.sln`, therefore `SOLUTION-ROOT` is `REPO-ROOT\Test\UnitTest`.
The `REPO-ROOT\Test\UnitTest\UnitTest\UnitTest.vcxproj` is the unit test project.

4
.github/Scripts/.gitignore vendored Normal file
View File

@@ -0,0 +1,4 @@
Build.log
Build.log.unfinished
Execute.log
Execute.log.unfinished

14
.github/TaskLogs/copilotBuild.ps1 → .github/Scripts/copilotBuild.ps1 vendored
View File

@@ -1,11 +1,9 @@
. $PSScriptRoot\copilotShared.ps1
# Remove log file if it exists
# Remove log files
$logFile = "$PSScriptRoot\Build.log"
if (Test-Path $logFile) {
Remove-Item $logFile -Force
Write-Host "Removed existing log file: $logFile"
}
$logFileUnfinished = "$logFile.unfinished"
Remove-Item -Path $logFile, $logFileUnfinished -Force -ErrorAction SilentlyContinue
# Find the solution folder by looking for *.sln files
$solutionFolder = GetSolutionDir
@@ -18,15 +16,13 @@ if ($vsdevcmd -eq $null) {
throw "$MESSAGE_1\r\n$MESSAGE_2"
}
# Execute msbuild with output to both console and log file
$Configuration = "Debug"
$Platform = "x64"
$msbuild_arguments = "MSBUILD `"$solutionFile`" /m:8 $rebuildControl /p:Configuration=`"$Configuration`";Platform=`"$Platform`""
$cmd_arguments = "`"`"$vsdevcmd`" & $msbuild_arguments"
# Execute msbuild with output to both console and log file
$logFile = "$PSScriptRoot\Build.log"
$commandLine = "/c $cmd_arguments"
$logFileUnfinished = "$logFile.unfinished"
& $env:ComSpec $commandLine 2>&1 | Tee-Object -FilePath $logFileUnfinished
Rename-Item -Path $logFileUnfinished -NewName $logFile -Force
exit $LASTEXITCODE
exit $LASTEXITCODE

0
.github/TaskLogs/copilotDebug_Init.txt → .github/Scripts/copilotDebug_Init.txt vendored
View File

0
.github/TaskLogs/copilotDebug_RunCommand.ps1 → .github/Scripts/copilotDebug_RunCommand.ps1 vendored
View File

0
.github/TaskLogs/copilotDebug_Start.ps1 → .github/Scripts/copilotDebug_Start.ps1 vendored
View File

0
.github/TaskLogs/copilotDebug_Stop.ps1 → .github/Scripts/copilotDebug_Stop.ps1 vendored
View File

10
.github/TaskLogs/copilotExecute.ps1 → .github/Scripts/copilotExecute.ps1 vendored
View File

@@ -5,12 +5,10 @@ param(
. $PSScriptRoot\copilotShared.ps1
# Remove log file if it exists
# Remove log files
$logFile = "$PSScriptRoot\Execute.log"
if (Test-Path $logFile) {
Remove-Item $logFile -Force
Write-Host "Removed existing log file: $logFile"
}
$logFileUnfinished = "$logFile.unfinished"
Remove-Item -Path $logFile, $logFileUnfinished -Force -ErrorAction SilentlyContinue
# Ensure the executable name has .exe extension
if ($Executable.EndsWith(".exe")) {
@@ -29,8 +27,6 @@ Write-Host "Selected $executableName`: $($latestFile.Path) (Modified: $($latestF
$debugArgs = GetDebugArgs $solutionFolder $latestFile $Executable
# Execute the selected executable with debug arguments and save output to log file
$logFile = "$PSScriptRoot\Execute.log"
$logFileUnfinished = "$logFile.unfinished"
$commandLine = "`"$($latestFile.Path)`" /C $debugArgs"
& { $commandLine; & cmd.exe /S /C $commandLine 2>&1 } | Tee-Object -FilePath $logFileUnfinished
Rename-Item -Path $logFileUnfinished -NewName $logFile -Force

22
.github/TaskLogs/copilotPrepare.ps1 → .github/Scripts/copilotPrepare.ps1 vendored
View File

@@ -20,7 +20,13 @@ $filesToCreate = @{
# Backup each markdown file for learning
$filesToBackup = @()
foreach ($file in $filesToOverride.GetEnumerator()) {
$filePath = "$PSScriptRoot\$($file.Key)"
$filePath = "$PSScriptRoot\..\TaskLogs\$($file.Key)"
if (Test-Path $filePath) {
$filesToBackup += $filePath
}
}
{
$filePath = "$PSScriptRoot\..\TaskLogs\Copilot_Execution_Finding.md"
if (Test-Path $filePath) {
$filesToBackup += $filePath
}
@@ -41,10 +47,18 @@ if ($filesToBackup.Count -gt 0) {
}
}
{
$filePath = "$PSScriptRoot\..\TaskLogs\Copilot_Execution_Finding.md"
if (Test-Path $filePath) {
Write-Host "Deleting Copilot_Execution_Finding.md..."
Remove-Item -Path $filePath -Force
}
}
if ($Backup) {
# Delete all files in $filesToOverride
foreach ($file in $filesToOverride.GetEnumerator()) {
$filePath = "$PSScriptRoot\$($file.Key)"
$filePath = "$PSScriptRoot\..\TaskLogs\$($file.Key)"
if (Test-Path $filePath) {
Write-Host "Deleting $($file.Key)..."
Remove-Item -Path $filePath -Force
@@ -53,14 +67,14 @@ if ($Backup) {
} else {
# Create each markdown file with the specified content
foreach ($file in $filesToOverride.GetEnumerator()) {
$filePath = "$PSScriptRoot\$($file.Key)"
$filePath = "$PSScriptRoot\..\TaskLogs\$($file.Key)"
Write-Host "Creating/overriding $($file.Key)..."
$file.Value | Out-File -FilePath $filePath -Encoding UTF8
}
# Create files only if they don't exist
foreach ($file in $filesToCreate.GetEnumerator()) {
$filePath = "$PSScriptRoot\$($file.Key)"
$filePath = "$PSScriptRoot\..\TaskLogs\$($file.Key)"
if (-not (Test-Path $filePath)) {
Write-Host "Creating $($file.Key)..."
$file.Value | Out-File -FilePath $filePath -Encoding UTF8

0
.github/TaskLogs/copilotShared.ps1 → .github/Scripts/copilotShared.ps1 vendored
View File

4
.github/TaskLogs/.gitignore vendored
View File

@@ -1,7 +1,3 @@
Copilot_Execution.md
Copilot_Planning.md
Copilot_Task.md
Build.log
Build.log.unfinished
Execute.log
Execute.log.unfinished

30
.github/TaskLogs/TaskLogs.vcxitems vendored
View File

@@ -1,30 +0,0 @@
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup Label="Globals">
<MSBuildAllProjects Condition="'$(MSBuildVersion)' == '' Or '$(MSBuildVersion)' &lt; '16.0'">$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
<HasSharedItems>true</HasSharedItems>
<ItemsProjectGuid>{8626528F-9C97-4480-A018-CDCCCB9CACAE}</ItemsProjectGuid>
</PropertyGroup>
<ItemDefinitionGroup>
<ClCompile>
<AdditionalIncludeDirectories>%(AdditionalIncludeDirectories);$(MSBuildThisFileDirectory)</AdditionalIncludeDirectories>
</ClCompile>
</ItemDefinitionGroup>
<ItemGroup>
<ProjectCapability Include="SourceItemsFromImports" />
</ItemGroup>
<ItemGroup>
<None Include="$(MSBuildThisFileDirectory)Copilot_KB.md" />
<None Include="$(MSBuildThisFileDirectory)Copilot_Execution.md" />
<None Include="$(MSBuildThisFileDirectory)Copilot_Planning.md" />
<None Include="$(MSBuildThisFileDirectory)Copilot_Task.md" />
<None Include="$(MSBuildThisFileDirectory)Copilot_Scrum.md" />
<None Include="$(MSBuildThisFileDirectory).gitignore" />
<None Include="$(MSBuildThisFileDirectory)copilotShared.ps1" />
<None Include="$(MSBuildThisFileDirectory)copilotPrepare.ps1" />
<None Include="$(MSBuildThisFileDirectory)copilotExecute.ps1" />
<None Include="$(MSBuildThisFileDirectory)copilotBuild.ps1" />
<None Include="$(MSBuildThisFileDirectory)copilotDebug_Start.ps1" />
<None Include="$(MSBuildThisFileDirectory)copilotDebug_Stop.ps1" />
<None Include="$(MSBuildThisFileDirectory)copilotDebug_RunCommand.ps1" />
</ItemGroup>
</Project>

557
.github/copilot-instructions.md vendored
View File

File diff suppressed because it is too large Load Diff

78
.github/prompts/win-0-scrum.prompt.md → .github/prompts/0-scrum.prompt.md vendored
View File

@@ -1,7 +1,8 @@
# Scrum
- Checkout `Accessing Log Files and PowerShell Scripts` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should already be existing, you should not create any new files.
- Check out `Accessing Task Documents` and `Accessing Script Files` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should exist; you should not create any new files unless explicitly instructed.
- Following `Leveraging the Knowledge Base` in `REPO-ROOT/.github/copilot-instructions.md`, find knowledge and documents for this project in `REPO-ROOT/.github/KnowledgeBase/Index.md`.
## Goal and Constraints
@@ -9,11 +10,11 @@
- You are only allowed to update `Copilot_Scrum.md`.
- You are not allowed to modify any other files.
- The phrasing of the request may look like asking for code change, but your actual work is to write the design document.
- "Task" in the request always mean a task under the `# TASKS` section in the design document.
- "Task" in the request always means a task under the `# TASKS` section in the design document.
## Copilot_Scrum.md Structure
- `# !!!SCRUM!!!`: This file always begin with this title.
- `# !!!SCRUM!!!`: This file always begins with this title.
- `# DESIGN REQUEST`: An exact copy of the problem description I gave you.
- `# UPDATES`: For multiple `## UPDATE` sections. It should always exist even there is no update.
- `## UPDATE`: There could be multiple occurrences. Each one has an exact copy of the update description I gave you.
@@ -28,9 +29,9 @@
## Step 1. Identify the Problem
- The problem I would like to solve is in the chat messages sending with this request.
- The problem I would like to solve is in the chat messages sent with this request.
- Find `# Problem` or `# Update` or `# Learn` in the LATEST chat message.
- Ignore any these titles in the chat history.
- Ignore any of these titles in the chat history.
- If there is nothing: it means you are accidentally stopped. Please continue your work.
### Create new Document (only when "# Problem" appears in the LATEST chat message)
@@ -130,7 +131,7 @@ I made important updates to the source code manually during the execution of the
- Ignore this section if there is no "# Learn" in the LATEST chat message
### Step 6.1. Identify the Last Complteted Task
### Step 6.1. Identify the Last Completed Task
- Identify the last completed task.
- The current `Copilot_Task.md`, `Copilot_Planning.md` and `Copilot_Execution.md` are associated to that task.
@@ -139,32 +140,32 @@ I made important updates to the source code manually during the execution of the
- Read through `Copilot_Execution.md`. There may be some fixing attempts, that were done by you.
- Compare existing source code with `Copilot_Execution.md`, finding what is changed.
- Don't rely on `git` to identify changes, as I always commit them periodaically. You need to compare the actual source code with `Copilot_Execution.md`.
- Don't rely on `git` to identify changes, as I always commit them periodically. You need to compare the actual source code with `Copilot_Execution.md`.
- During comparing, you need to take into consideration of the fixing attempts, as sometimes you didn't update the main content of the document.
- Identify all differences between the document and the source code:
- If it is caused by any fixing attempts, ignore it.
- If it is caused by any `# UPDATE`, ignore it.
- If any fixing attempt was reverted:
- It may be canceled by a further fixing attemp, ignore it.
- It may be canceled by a further fixing attempt, ignore it.
- Otherwise it was a user edit.
- Any other difference is a user edit.
- If there is no `# !!!VERIFIED!!!` in `Copilot_Execution.md`, it means you failed to deliver the task, either the code did not compile or some test cases failed. My edit will also reflects the final solution to the task.
- Carefully read through and analyse all user edits, understand my tastes and preferences about the source code.
- If there is no `# !!!VERIFIED!!!` in `Copilot_Execution.md`, it means you failed to deliver the task, either the code did not compile or some test cases failed. My edit will also reflect the final solution to the task.
- Carefully read through and analyze all user edits, understand my tastes and preferences about the source code.
### Step 6.3 Write Down Findings
- If every changes are ignored by the rule above, skip thi step.
- If every change is ignored by the rule above, skip this step.
- Create a new file `Copilot_Execution_Finding.md` with a topic `# Comparing to User Edit`.
- `Copilot_Execution_Finding.md` should stay in the same folder as `Copilot_Execution.md`.
- Add your finding to `Copilot_Execution_Finding.md`.
### Step 6.4 Learn
- There will be multiple `# UPDATES` or `# FIXING ATTEMPTS` or `# Comparing to User Edit` sections in `Copilot_Task.md`, `Copilot_Planning.md` and `Copilot_Execution.md`.
- These 3 files recorded how you interpreted the last completed task, and how I wanted you to adjust your understanding.
- There will be multiple `# UPDATES` or `# FIXING ATTEMPTS` or `# Comparing to User Edit` sections in `Copilot_Task.md`, `Copilot_Planning.md`, `Copilot_Execution.md` and `Copilot_Execution_Finding.md`.
- These 3 files recorded how you interpreted the last completed task, and how I wanted you to adjust your understanding.
- Find out what you can learn from the updates, about my philosophy and preferences.
- Check all future tasks, apply what you have learned, and adjust your approach accordingly.
- For each unfinished tasks that can be improved, update releated learnings in `Copilot_Scrum.md`.
- For each unfinished task that can be improved, update related learnings in `Copilot_Scrum.md`.
### Step 6.5 Backup
@@ -172,49 +173,4 @@ I made important updates to the source code manually during the execution of the
- In the above steps, necessary change will be updated to `Copilot_Execution.md` and `Copilot_Scrum.md`.
- Find and execute `copilotPrepare.ps1 -Backup`. You MUST use the `-Backup` parameter.
- Remember the first line of the output, it has the absolute path to the backup folder.
- By running the backup script, `Copilot_Task.md`, `Copilot_Planning.md` and `Copilot_Execution.md` will be backed up and deleted.
- If you created `Copilot_Execution_Finding.md`, in Step 6.3:
- In the backup folder, there will be a copied `Copilot_Execution.md`, append all contents from `Copilot_Execution_Finding.md` to the end of it.
- Delete the `Copilot_Execution_Finding.md` you created.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Accessing Log Files and PowerShell Scripts
This guidance is for accessing following files mentioned in this instruction:
- `Copilot_Scrum.md`
- `Copilot_Task.md`
- `Copilot_Planning.md`
- `Copilot_Execution.md`
- `Copilot_KB.md`
- `copilotPrepare.ps1`
- `copilotBuild.ps1`
- `copilotExecute.ps1`
- `copilotDebug_Start.ps1`
- `copilotDebug_Stop.ps1`
- `copilotDebug_RunCommand.ps1`
- `Build.log`
- `Execute.log`
They are in the `REPO-ROOT/.github/TaskLogs` folder. `REPO-ROOT` is the root folder of the repo.
## If you are running in Visual Studio
You will find the `TaskLogs` project in the current solution, which should contain these files.
## Important Rules for Markdown Document or Log
- Do not print "````````" or "````````markdown" in markdown file.
- It is totally fine to have multiple top level `# Topic`.
- When mentioning a C++ name in markdown file:
- If it is defined in the standard C++ library or third-party library, use the full name.
- If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.
- By running the backup script, `Copilot_Task.md`, `Copilot_Planning.md`, `Copilot_Execution.md` and `Copilot_Execution_Finding.md` will be backed up and deleted.

70
.github/prompts/win-1-design.prompt.md → .github/prompts/1-design.prompt.md vendored
View File

@@ -1,30 +1,32 @@
# Design
- Checkout `Accessing Log Files and PowerShell Scripts` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should already be existing, you should not create any new files.
- Check out `Accessing Task Documents` and `Accessing Script Files` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should exist; you should not create any new files unless explicitly instructed.
- Following `Leveraging the Knowledge Base` in `REPO-ROOT/.github/copilot-instructions.md`, find knowledge and documents for this project in `REPO-ROOT/.github/KnowledgeBase/Index.md`.
## Goal and Constraints
- Your goal is to finish a design document in `Copilot_Task.md` to address a problem.
- You are only allowed to update `Copilot_Task.md` and mark a task completed in `Copilot_Scrum.md`.
- You are only allowed to update `Copilot_Task.md` and mark a task being taken in `Copilot_Scrum.md`.
- You are not allowed to modify any other files.
- The phrasing of the request may look like asking for code change, but your actual work is to write the design document.
## Copilot_Task.md Structure
- `# !!!TASK!!!`: This file always begin with this title.
- `# !!!TASK!!!`: This file always begins with this title.
- `# PROBLEM DESCRIPTION`: An exact copy of the problem description I gave you.
- `# UPDATES`: For multiple `## UPDATE` sections. It should always exist even there is no update.
- `## UPDATE`: There could be multiple occurrences. Each one has an exact copy of the update description I gave you.
- `# INSIGHTS AND REASONING`.
- `# AFFECTED PROJECTS`.
## Step 1. Identify the Problem
- The problem I would like to solve is in the chat messages sending with this request.
- The problem I would like to solve is in the chat messages sent with this request.
- Find `# Problem` or `# Update` in the LATEST chat message.
- Ignore any these titles in the chat history.
- Ignore any of these titles in the chat history.
- If there is nothing: it means you are accidentally stopped. Please continue your work.
- Read `Copilot_Task.md` througly, it is highly possibly that you were working on the request described in the last section in `# PROBLEM DESCRIPTION`.
- Read `Copilot_Task.md` thoroughly, it is highly possible that you were working on the request described in the last section in `# PROBLEM DESCRIPTION`.
### Create new Document (only when "# Problem" appears in the LATEST chat message)
@@ -34,11 +36,11 @@ I am starting a fresh new request.
- Find and execute `copilotPrepare.ps1` to clean up everything from the last run.
- After `copilotPrepare.ps1` finishes, copy precisely my problem description in `# Problem` from the LATEST chat message under a `# PROBLEM DESCRIPTION`.
- If the problem description is `Next`:
- Find the first incomplete task in `Copilot_Scrum.md`, and follow the intruction below to process that task.
- Find the first incomplete task in `Copilot_Scrum.md`.
- If the problem description is like `Complete task No.X`:
- Locate the specific task in `Copilot_Scrum.md`.
- There is a bullet list of all tasks at the beginning of `# TASKS`. Mark the specific task as being processed by changing `[ ]` to `[x]`.
- Find the details of the specific task, copy everything in this task to `# PROBLEM DESCRIPTION`.
- There is a bullet list of all tasks at the beginning of `# TASKS`. Mark the specific task as being taken by changing `[ ]` to `[x]`.
- Find the details of the specific task, copy everything in this task to `# PROBLEM DESCRIPTION`.
- Add an empty `# UPDATES` section after `# PROBLEM DESCRIPTION`.
### Update current Document (only when "# Update" appears in the LATEST chat message)
@@ -77,49 +79,13 @@ I am going to propose some change to `Copilot_Task.md`.
- Your goal is to write a design document to `Copilot_Task.md`. DO NOT update any other file including source code.
- Whatever you think or found, write it down in the `# INSIGHTS AND REASONING` section.
- Fill the `# AFFECTED PROJECTS` section:
- Solutions and projects you need to work on could be found in `REPO-ROOT/.github/Project.md`.
- Complete this section in this format:
- Identify affected solutions, write `- Build the solution in folder <SOLUTION-ROOT>`.
- For each solution, identify affected unit test projects, write ` - Run Test Project <PROJECT-NAME>`.
- The list should only include unit test projects.
## Step 4. Mark the Completion
- Ensure there is a `# !!!FINISHED!!!` mark at the end of `Copilot_Task.md` to indicate the document reaches the end.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Accessing Log Files and PowerShell Scripts
This guidance is for accessing following files mentioned in this instruction:
- `Copilot_Scrum.md`
- `Copilot_Task.md`
- `Copilot_Planning.md`
- `Copilot_Execution.md`
- `Copilot_KB.md`
- `copilotPrepare.ps1`
- `copilotBuild.ps1`
- `copilotExecute.ps1`
- `copilotDebug_Start.ps1`
- `copilotDebug_Stop.ps1`
- `copilotDebug_RunCommand.ps1`
- `Build.log`
- `Execute.log`
They are in the `REPO-ROOT/.github/TaskLogs` folder. `REPO-ROOT` is the root folder of the repo.
## If you are running in Visual Studio
You will find the `TaskLogs` project in the current solution, which should contain these files.
## Important Rules for Markdown Document or Log
- Do not print "````````" or "````````markdown" in markdown file.
- It is totally fine to have multiple top level `# Topic`.
- When mentioning a C++ name in markdown file:
- If it is defined in the standard C++ library or third-party library, use the full name.
- If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.

68
.github/prompts/win-2-planning.prompt.md → .github/prompts/2-planning.prompt.md vendored
View File

@@ -1,7 +1,8 @@
# Planning
- Checkout `Accessing Log Files and PowerShell Scripts` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should already be existing, you should not create any new files.
- Check out `Accessing Task Documents` and `Accessing Script Files` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should exist; you should not create any new files unless explicitly instructed.
- Following `Leveraging the Knowledge Base` in `REPO-ROOT/.github/copilot-instructions.md`, find knowledge and documents for this project in `REPO-ROOT/.github/KnowledgeBase/Index.md`.
## Goal and Constraints
@@ -12,9 +13,10 @@
## Copilot_Planning.md Structure
- `# !!!PLANNING!!!`: This file always begin with this title.
- `# !!!PLANNING!!!`: This file always begins with this title.
- `# UPDATES`: For multiple `## UPDATE` sections. It should always exist even there is no update.
- `## UPDATE`: There could be multiple occurrences. Each one has an exact copy of the update description I gave you.
- `# AFFECTED PROJECTS`.
- `# EXECUTION PLAN`.
- `## STEP X: The Step Title`: One step in the improvement plan.
- A clear description of what to change in the source code.
@@ -24,9 +26,9 @@
- The design document is in `Copilot_Task.md`. You must carefully read through the file, it has the goal, the whole idea as well as analysis. If `Copilot_Task.md` mentions anything about updating the knowledge base, ignore it.
- Find `# Problem` or `# Update` in the LATEST chat message.
- Ignore any these titles in the chat history.
- Ignore any of these titles in the chat history.
- If there is nothing: it means you are accidentally stopped. Please continue your work.
- Read `Copilot_Planning.md` througly, it is highly possibly that you were working on the request described in the last section in `# UPDATES`.
- Read `Copilot_Planning.md` thoroughly, it is highly possible that you were working on the request described in the last section in `# UPDATES`.
### Create new Document (only when "# Problem" appears in the LATEST chat message)
@@ -42,17 +44,17 @@ Ignore this section if there is no "# Update" in the LATEST chat message
I am going to propose some change to `Copilot_Planning.md`.
- Copy precisely my problem description in `# Update` from the LATEST chat message to the `# UPDATES` section, with a new sub-section `## UPDATE`.
- The new `## UPDATE` should be appended to the end of the existing `# UPDATES` section (aka before `# EXECUTION PLAN`).
- The new `## UPDATE` should be appended to the end of the existing `# UPDATES` section (aka before `# AFFECTED PROJECTS`).
- Follow my update to change the planning document.
## Step 2. Understand the Goal and Quality Requirement
- You need to write complete two main sections in `Copilot_Planning.md`, an improvement plan and a test plan.
- You need to write two complete main sections in `Copilot_Planning.md`, an improvement plan and a test plan.
- Read through and understand the task in `Copilot_Task.md`.
### Tips for a Feature Planning Task
- C++ source files depends on each other, by just implementing the task it may not enough. Find out what will be affected.
- C++ source files depend on each other, by just implementing the task it may not be enough. Find out what will be affected.
- Propose any code change you would like to do. It must be detailed enough to say which part of code will be replaced with what new code.
- Explain why you want to make these changes.
- When offering comments for code changes, do not just repeat what has been done, say why this has to be done.
@@ -69,51 +71,15 @@ I am going to propose some change to `Copilot_Planning.md`.
## Step 3. Finish the Document
- Your goal is to write a design document to `Copilot_Planning.md`. DO NOT update any other file including source code.
- The code change proposed in the improvement plan must contain actual code. I need to review them before going to the next phrase.
- The code change proposed in the improvement plan must contain actual code. I need to review them before going to the next phase.
- DO NOT copy `# UPDATES` from `Copilot_Task.md` to `Copilot_Planning.md`.
- Fill the `# AFFECTED PROJECTS` section:
- Solutions and projects you need to work on could be found in `REPO-ROOT/.github/Project.md`.
- When creating `Copilot_Planning.md` from the first time, copy `# AFFECTED PROJECTS` section from `Copilot_Task.md`. Otherwise, review the list whenever `Copilot_Planning.md` is updated, and fix this section in the following format:
- Identify affected solutions, write `- Build the solution in folder <SOLUTION-ROOT>`.
- For each solution, identify affected unit test projects, write ` - Run Test Project <PROJECT-NAME>`.
- The list should only include unit test projects.
## Step 4. Mark the Completion
- Ensure there is a `# !!!FINISHED!!!` mark at the end of `Copilot_Planning.md` to indicate the document reaches the end.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Accessing Log Files and PowerShell Scripts
This guidance is for accessing following files mentioned in this instruction:
- `Copilot_Scrum.md`
- `Copilot_Task.md`
- `Copilot_Planning.md`
- `Copilot_Execution.md`
- `Copilot_KB.md`
- `copilotPrepare.ps1`
- `copilotBuild.ps1`
- `copilotExecute.ps1`
- `copilotDebug_Start.ps1`
- `copilotDebug_Stop.ps1`
- `copilotDebug_RunCommand.ps1`
- `Build.log`
- `Execute.log`
They are in the `REPO-ROOT/.github/TaskLogs` folder. `REPO-ROOT` is the root folder of the repo.
## If you are running in Visual Studio
You will find the `TaskLogs` project in the current solution, which should contain these files.
## Important Rules for Markdown Document or Log
- Do not print "````````" or "````````markdown" in markdown file.
- It is totally fine to have multiple top level `# Topic`.
- When mentioning a C++ name in markdown file:
- If it is defined in the standard C++ library or third-party library, use the full name.
- If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.

66
.github/prompts/win-3-summarizing.prompt.md → .github/prompts/3-summarizing.prompt.md vendored
View File

@@ -1,7 +1,8 @@
# Summarizing
- Checkout `Accessing Log Files and PowerShell Scripts` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should already be existing, you should not create any new files.
- Check out `Accessing Task Documents` and `Accessing Script Files` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should exist; you should not create any new files unless explicitly instructed.
- Following `Leveraging the Knowledge Base` in `REPO-ROOT/.github/copilot-instructions.md`, find knowledge and documents for this project in `REPO-ROOT/.github/KnowledgeBase/Index.md`.
## Goal and Constraints
@@ -12,9 +13,10 @@
## Copilot_Execution.md Structure
- `# !!!EXECUTION!!!`: This file always begin with this title.
- `# !!!EXECUTION!!!`: This file always begins with this title.
- `# UPDATES`: For multiple `## UPDATE` sections. It should always exist even there is no update.
- `## UPDATE`: There could be multiple occurrences. Each one has an exact copy of the update description I gave you.
- `# AFFECTED PROJECTS`.
- `# EXECUTION PLAN`.
- `# FIXING ATTEMPTS`.
@@ -22,7 +24,7 @@
- The design document is in `Copilot_Task.md`, the planning document is in `Copilot_Planning.md`.
- Find `# Problem` or `# Update` in the LATEST chat message.
- Ignore any these titles in the chat history.
- Ignore any of these titles in the chat history.
- If there is nothing:
- If there is a `# !!!FINISHED!!!` mark in `Copilot_Execution.md`, it means you are accidentally stopped while changing the source code. Please continue your work.
- If there is no `# !!!FINISHED!!!` mark in `Copilot_Execution.md`, it means you are accidentally stopped while finishing the document. Please continue your work.
@@ -41,13 +43,13 @@ Ignore this section if there is no "# Update" in the LATEST chat message
I am going to propose some change to `Copilot_Execution.md`.
- Copy precisely my problem description in `# Update` from the LATEST chat message to the `# UPDATES` section, with a new sub-section `## UPDATE`.
- The new `## UPDATE` should be appended to the end of the existing `# UPDATES` section (aka before `# EXECUTION PLAN`).
- The new `## UPDATE` should be appended to the end of the existing `# UPDATES` section (aka before `# AFFECTED PROJECTS`).
- Follow my update to change the execution document.
## Step 2. Finish the Document
- Your need to summary code change in `Copilot_Execution.md`.
- All changes you need to made is already in `Copilot_Planning.md`, but it contains many explanations.
- You need to summarize code change in `Copilot_Execution.md`.
- All changes you need to make are already in `Copilot_Planning.md`, but it contains many explanations.
- Read `Copilot_Planning.md`, copy the following parts to `Copilot_Execution.md`:
- `# EXECUTION PLAN`
- Copy EVERY code block exactly as written
@@ -68,49 +70,13 @@ I am going to propose some change to `Copilot_Execution.md`.
## Step 3. Document Quality Check List
- Is `Copilot_Execution.md` contains enough information so that one can follow the document to make actual code change, without having to refer to `Copilot_Planning.md`?
- Is `Copilot_Execution.md` include all code changes mentioned in `Copilot_Planning.md`?
- Does `Copilot_Execution.md` include all code changes mentioned in `Copilot_Planning.md`?
- Fill the `# AFFECTED PROJECTS` section:
- Solutions and projects you need to work on could be found in `REPO-ROOT/.github/Project.md`.
- When creating `Copilot_Execution.md` from the first time, copy `# AFFECTED PROJECTS` section from `Copilot_Planning.md`. Otherwise, review the list whenever `Copilot_Execution.md` is updated, and fix this section in the following format:
- Identify affected solutions, write `- Build the solution in folder <SOLUTION-ROOT>`.
- For each solution, identify affected unit test projects, write ` - Run Test Project <PROJECT-NAME>`.
- The list should only include unit test projects.
## Step 4. Completion
- Ensure there is a `# !!!FINISHED!!!` mark at the end of `Copilot_Execution.md` to indicate the document reaches the end.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Accessing Log Files and PowerShell Scripts
This guidance is for accessing following files mentioned in this instruction:
- `Copilot_Scrum.md`
- `Copilot_Task.md`
- `Copilot_Planning.md`
- `Copilot_Execution.md`
- `Copilot_KB.md`
- `copilotPrepare.ps1`
- `copilotBuild.ps1`
- `copilotExecute.ps1`
- `copilotDebug_Start.ps1`
- `copilotDebug_Stop.ps1`
- `copilotDebug_RunCommand.ps1`
- `Build.log`
- `Execute.log`
They are in the `REPO-ROOT/.github/TaskLogs` folder. `REPO-ROOT` is the root folder of the repo.
## If you are running in Visual Studio
You will find the `TaskLogs` project in the current solution, which should contain these files.
## Important Rules for Markdown Document or Log
- Do not print "````````" or "````````markdown" in markdown file.
- It is totally fine to have multiple top level `# Topic`.
- When mentioning a C++ name in markdown file:
- If it is defined in the standard C++ library or third-party library, use the full name.
- If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.

80
.github/prompts/4-execution.prompt.md vendored Normal file
View File

@@ -0,0 +1,80 @@
# Execution
- Check out `Accessing Task Documents` and `Accessing Script Files` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should exist; you should not create any new files unless explicitly instructed.
- Following `Leveraging the Knowledge Base` in `REPO-ROOT/.github/copilot-instructions.md`, find knowledge and documents for this project in `REPO-ROOT/.github/KnowledgeBase/Index.md`.
## Goal and Constraints
- You are going to apply changes to the source code following `Copilot_Execution.md`.
## Copilot_Execution.md Structure
- `# !!!EXECUTION!!!`: This file always begins with this title.
- `# UPDATES`:
- `## UPDATE`: There could be multiple occurrences. Each one has an exact copy of the update description I gave you.
- `# EXECUTION PLAN`.
- `# FIXING ATTEMPTS`.
## Step 1. Identify the Problem
- The execution document is in `Copilot_Execution.md`
- Find `# Update` in the LATEST chat message.
- Ignore any of these titles in the chat history.
### Execute the Plan (only when no title appears in the LATEST chat message)
Ignore this section if there is any title in the LATEST chat message
I am starting a fresh new request.
- Apply all code changes in `Copilot_Execution.md` to the source code.
- Make sure indentation and line breaks are applied correctly, following the same style in the target file.
- After applying each step in `Copilot_Execution.md`, mark the step as completed by appending `[DONE]` after the step title. This allows you to find where you are if you are interrupted.
### Update the Source Code and Document (only when "# Update" appears in the LATEST chat message)
Ignore this section if there is no "# Update" in the LATEST chat message
I am going to propose some change to the source code.
- Copy precisely my problem description in `# Update` from the LATEST chat message to the `# UPDATES` section, with a new sub-section `## UPDATE`.
- Follow my update to change the source code.
- Update the document to keep it consistent with the source code.
## Step 2. Make Sure the Code Compiles but DO NOT Run Unit Test
- Check out `External Tools Environment and Context` in `REPO-ROOT/.github/copilot-instructions.md` for accessing scripts for building.
- Strictly follow the instruction above as this repo does not use ordinary tools.
- Each attempt of build-fix process should be executed in a sub agent.
- One build-fix process includes one attempt following `Build Unit Test` and `Fix Compile Errors`.
- The main agent should call different sub agent for each build-fix process.
- Do not build and retrieve build results in the main agent.
### Use a sub agent to run the following instructions (`Build Unit Test` and `Fix Compile Errors`)
#### Build Unit Test
- Check out `# AFFECTED PROJECTS` in `Copilot_Execution.md` to find out what solutions you need to build.
- Find out if there is any warning or error.
- `External Tools Environment and Context` has the instruction about how to check compile result.
#### Fix Compile Errors
- If there is any compilation error, address all of them:
- If there is any compile warning, only fix warnings that caused by your code change. Do not fix any other warnings.
- If there is any compile error, you need to carefully identify, is the issue in the callee side or the caller side. Check out similar code before making a decision.
- For every attempt of fixing the source code:
- Explain why the original change did not work.
- Explain what you need to do.
- Explain why you think it would solve the build break.
- Log these in `Copilot_Execution.md`, with section `## Fixing attempt No.<attempt_number>` in `# FIXING ATTEMPTS`.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Make Sure the Code Compiles but DO NOT Run Unit Test`.
- When the code compiles:
- DO NOT run any tests, the code will be verified in future tasks.
## Step 3. Verify Coding Style
- Code changes in `Copilot_Execution.md` may not have correct indentation and coding style.
- Go over each code change and ensure:
- Indentation is correct and consistent with the surrounding code.
- Coding style especially line breaks follows the same conventions as the surrounding code.
- Ensure any empty line does not contain spaces or tabs.

99
.github/prompts/5-verifying.prompt.md vendored Normal file
View File

@@ -0,0 +1,99 @@
# Verifying
- Check out `Accessing Task Documents` and `Accessing Script Files` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should exist; you should not create any new files unless explicitly instructed.
- Following `Leveraging the Knowledge Base` in `REPO-ROOT/.github/copilot-instructions.md`, find knowledge and documents for this project in `REPO-ROOT/.github/KnowledgeBase/Index.md`.
## Goal and Constraints
- All instructions in `Copilot_Execution.md` should have been applied to the source code, your goal is to test it.
- You must ensure the source code compiles.
- You must ensure all tests pass.
- Until the code compiles and all test cases pass, ensure there is a `# !!!VERIFIED!!!` mark at the end of `Copilot_Execution.md`.
## Step 1. Check and Respect my Code Change
- If you spot any difference between `Copilot_Execution.md` and the source code:
- It means I edited them. I have my reason. DO NOT change the code to match `Copilot_Execution.md`.
- Write down every difference you spotted, make a `## User Update Spotted` section in the `# UPDATES` section in `Copilot_Execution.md`.
## Step 2. Compile
- Check out `External Tools Environment and Context` in `REPO-ROOT/.github/copilot-instructions.md` for accessing scripts for building.
- Strictly follow the instruction above as this repo does not use ordinary tools.
- Each attempt of build-fix process should be executed in a sub agent.
- One build-fix process includes one attempt following `Build Unit Test` and `Fix Compile Errors`.
- The main agent should call different sub agent for each build-fix process.
- Do not build and retrieve build results in the main agent.
### Use a sub agent to run the following instructions (`Build Unit Test` and `Fix Compile Errors`)
#### Build Unit Test
- Check out `# AFFECTED PROJECTS` in `Copilot_Execution.md` to find out what solutions you need to build.
- Find out if there is any warning or error.
- `External Tools Environment and Context` has the instruction about how to check compile result.
#### Fix Compile Errors
- If there is any compilation error, address all of them:
- If there is any compile warning, only fix warnings that caused by your code change. Do not fix any other warnings.
- If there is any compile error, you need to carefully identify, is the issue in the callee side or the caller side. Check out similar code before making a decision.
- For every attempt of fixing the source code:
- Explain why the original change did not work.
- Explain what you need to do.
- Explain why you think it would solve the build break or test break.
- Log these in `Copilot_Execution.md`, with section `## Fixing attempt No.<attempt_number>` in `# FIXING ATTEMPTS`.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
## Step 3. Run Unit Test
- Check out `External Tools Environment and Context` in `REPO-ROOT/.github/copilot-instructions.md` for accessing scripts for testing and debugging.
- Strictly follow the instruction above as this repo does not use ordinary tools.
- Each attempt of test-fix process should be executed in a sub agent.
- One test-fix process includes one attempt following `Execute Unit Test` and `Fix Failed Test Cases`.
- The main agent should call different sub agent for each test-fix process.
- Do not test and retrieve test results in the main agent.
### Use a sub agent to run the following instructions (`Execute Unit Test`, `Identify the Cause of Failure` and `Fix Failed Test Cases`)
#### Execute Unit Test
- Check out `# AFFECTED PROJECTS` in `Copilot_Execution.md` to find out what projects you need to execute.
- Run the unit test and see if they passed. If anything is good, you will only see test files and test cases that are executed.
- Make sure added test cases are actually executed.
- If any test case fails on a test assertion, the content of `TEST_ASSERT` or other macros will be printed to the output.
- If any test case crashes, the failed test case will be the last one printed. In this case, you might need to add logging to the code.
- In any test case, `TEST_PRINT` would help.
- In other source code, `vl::console::Console::WriteLine` would help. In `Vlpp` project, you should `#include` `Console.h`. In other projects, the `Console` class should just be available.
- When added logging are not longer necessary, you should remove all of them.
#### Identify the Cause of Failure
- You can refer to `Copilot_Task.md` and `Copilot_Planning.md` to understand the context, keep the target unchanged.
- Dig into related source code carefully, make your assumption about the root cause.
- `TEST_ASSERT` in test cases or `vl::console::Console::WriteLine` in the source code would help.
- They can make sure the expected code path is executed.
- They can print variable values after converting to strings.
- Debug the unit test directly to get accurate clues if you are not confident of the assumption
- Follow `Debugging a Project` to start a debugger and run WinDBG commands.
- From there you can set break-points, walk through code by lines, and inspect variables.
- You must stop the debugger after you finish debugging.
- When you have made a few guesses but did not progress, you are recommended to debug the unit test directly.
- Break-points are very useful to ensure the expected code path is executed, and you can inspect variable values.
#### Fix Failed Test Cases
- Apply fixings to source files.
- DO NOT delete any test case.
- For every attempt of fixing the source code:
- Explain why the original change did not work.
- Explain what you need to do.
- Explain why you think it would solve the build break or test break.
- Log these in `Copilot_Execution.md`, with section `## Fixing attempt No.<attempt_number>` in `# FIXING ATTEMPTS`.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
- `Step 2. Compile` and `Step 3. Run Unit Test` are absolutely no problem. If you didn't see any progress, the only reason is that your change is not correct.
## Step 4. Check it Again
- Go back to `Step 2. Compile`, follow all instructions and all steps again.

6
.github/prompts/ask.prompt.md vendored Normal file
View File

@@ -0,0 +1,6 @@
# Analysis
- This is analysis work, DO NOT update any source code.
- Find out the `Leveraging the Knowledge Base` section. Understand the organization of the knowledge base.
- You are in a large C++ project, you must try your best to read any source code that may possibly be related to the analysis work.
- Follow the chat message, try your best to answer the analysis work.

83
.github/prompts/code.prompt.md vendored Normal file
View File

@@ -0,0 +1,83 @@
# Task
- Check out `Accessing Task Documents` and `Accessing Script Files` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should exist; you should not create any new files unless explicitly instructed.
## Goal and Constraints
- You must ensure the source code compiles.
- You must ensure all tests pass.
## Step 1. Implement Request
- Follow the chat message to implement the task.
## Step 2. Compile
- Check out `External Tools Environment and Context` in `REPO-ROOT/.github/copilot-instructions.md` for accessing scripts for building.
- Strictly follow the instruction above as this repo does not use ordinary tools.
- Each attempt of build-fix process should be executed in a sub agent.
- One build-fix process includes one attempt following `Build Unit Test` and `Fix Compile Errors`.
- The main agent should call different sub agent for each build-fix process.
- Do not build and retrieve build results in the main agent.
### Use a sub agent to run the following instructions (`Build Unit Test` and `Fix Compile Errors`)
#### Build Unit Test
- Check out `REPO-ROOT/.github/Project.md` to find out what solutions you need to build.
- Find out if there is any warning or error.
- `External Tools Environment and Context` has the instruction about how to check compile result.
#### Fix Compile Errors
- If there is any compilation error, address all of them:
- If there is any compile warning, only fix warnings that caused by your code change. Do not fix any other warnings.
- If there is any compile error, you need to carefully identify, is the issue in the callee side or the caller side. Check out similar code before making a decision.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
## Step 3. Run Unit Test
- Check out `External Tools Environment and Context` in `REPO-ROOT/.github/copilot-instructions.md` for accessing scripts for testing and debugging.
- Strictly follow the instruction above as this repo does not use ordinary tools.
- Each attempt of test-fix process should be executed in a sub agent.
- One test-fix process includes one attempt following `Execute Unit Test` and `Fix Failed Test Cases`.
- The main agent should call different sub agent for each test-fix process.
- Do not test and retrieve test results in the main agent.
### Use a sub agent to run the following instructions (`Execute Unit Test`, `Identify the Cause of Failure` and `Fix Failed Test Cases`)
#### Execute Unit Test
- Check out `REPO-ROOT/.github/Project.md` to find out what projects you need to execute.
- Run the unit test and see if they passed. If everything is good, you will only see test files and test cases that are executed.
- Make sure added test cases are actually executed.
- If any test case fails on a test assertion, the content of `TEST_ASSERT` or other macros will be printed to the output.
- If any test case crashes, the failed test case will be the last one printed. In this case, you might need to add logging to the code.
- In any test case, `TEST_PRINT` would help.
- In other source code, `vl::console::Console::WriteLine` would help. In `Vlpp` project, you should `#include` `Console.h`. In other projects, the `Console` class should just be available.
- When added logging is no longer necessary, you should remove all of them.
#### Identify the Cause of Failure
- Dig into related source code carefully, make your assumption about the root cause.
- `TEST_ASSERT` in test cases or `vl::console::Console::WriteLine` in the source code would help.
- They can make sure the expected code path is executed.
- They can print variable values after converting to strings.
- Debug the unit test directly to get accurate clues if you are not confident of the assumption
- Follow `Debugging a Project` to start a debugger and run WinDBG commands.
- From there you can set break-points, walk through code by lines, and inspect variables.
- You must stop the debugger after you finish debugging.
- When you have made a few guesses but did not progress, you are recommended to debug the unit test directly.
- Break-points are very useful to ensure the expected code path is executed, and you can inspect variable values.
#### Fix Failed Test Cases
- Apply fixes to source files.
- DO NOT delete any test case.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
- `Step 2. Compile` and `Step 3. Run Unit Test` are absolutely no problem. If you didn't see any progress, the only reason is that your change is not correct.
## Step 4. Check it Again
- Go back to `Step 2. Compile`, follow all instructions and all steps again.

19
.github/prompts/win-kb-api.prompt.md → .github/prompts/kb-api.prompt.md vendored
View File

@@ -5,31 +5,20 @@
## Implement the Knowledge Base
- Find out the `Accessing the Knowledge Base` section. Understand the organization of the knowledge base.
- Find out the `Leveraging the Knowledge Base` section. Understand the organization of the knowledge base.
- Read the `Index.md` of the knowledge base first.
- There could be multiple places as the request might include multiple objectives. For each objective:
- Find out which project does it belong to.
- Read through all categories, find out which category is the best fit.
- If there is no obvious best answer, create a new category.A new category comes with a new guideline file, you must add it to the `KnowledgeBase` project.
- If there is no obvious best answer, create a new category. A new category comes with a new guideline file, you must add it to the `KnowledgeBase` project.
- Please be careful about the place to insert the new category, a new category should be added at the end of the belonging project.
- Update the category description if you think there is anything worth menthioning.
- Update the category description if you think there is anything worth mentioning.
- Read through the file of the hyperlink in the category, update the content to reflect the change I want you to make.
## Adding or Updating an `API Explanation` guideline
- Content in such guideline must be compact. Do not repeat anything that could be read from the source code.
- Do not simply add code samples.
- If you do, keep the code sample stick to only usage of APIs.
- If you do, keep the code sample sticking to only usage of APIs.
- Do not add code sample just to show best practices or what it can do or what it is commonly used or something like that, describe these topics in words.
- A code sample is only necessary when many functions or classes must be involved in a specific order. A good example would be the `TEST_FILE` structure.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.

56
.github/prompts/win-kb-design.prompt.md → .github/prompts/kb-design.prompt.md vendored
View File

@@ -34,21 +34,21 @@
- Find `Steps for Execute` section for the complete instructions.
- If there is nothing: it means you are accidentally stopped. Please continue your work.
- Read `Copilot_KB.md` througly, it is highly possibly that you were working on the request described in the last section in `# DOCUMENT REQUEST`.
- Read `Copilot_KB.md` thoroughly, it is highly possible that you were working on the request described in the last section in `# DOCUMENT REQUEST`.
- Existing content in `# DOCUMENT REQUEST` should be frozen, you can change it only when you find out the analysis is incorrect during my clarification (try limit the scope to `## TOPIC`).
- Existing content in `# DOCUMENT REQUEST` should be frozen, you can change it only when you find out the analysis is incorrect during my clarification (try to limit the scope to `## TOPIC`).
## Steps for Topic
- Your goal is to complete a `### Insight` section in the `## TOPIC` of the `# DOCUMENT REQUEST` section.
- The topic I would like you to research about is in the `# Topic` section in the LATEST chat message.
- The topic is around a feature of the project. It involves multiple places of the source code across many components.
- You need to find out the details of the code logic abount:
- You need to find out the details of the code logic about:
- The entry point.
- The core part.
- Whether there are multiple branches of cases, find all of them.
- Whether there are recursive calls, find the structure.
- Explain in details about the design and:
- Explain in detail about the design and:
- architecture
- organization of components
- execution flows
@@ -79,13 +79,13 @@
- But at the moment only edit `Copilot_KB.md`, do not edit `Index.md`. You are drafting a document, it will be implemented in `Index.md` only after my approval.
- Make a `# DRAFT-TITLE` section, you need to make a comprehensive but short title for the draft document.
- Make a `# DRAFT-CONTENT` section, you need to complete the content of the draft document here.
- The draft document is completedly based on the source code of the project, and all findings in the `# DOCUMENT REQUEST` section.
- The draft document is completely based on the source code of the project, and all findings in the `# DOCUMENT REQUEST` section.
- You must not miss any details, you must use every single point mentioned in the document.
- Since `# DOCUMENT REQUEST` is organized as multiple rounds of questions and answers, it cannot be just directly used as a document. You must reorganize them.
- Similar knowledges under the same categories might be spread in different answers, pay attention to them, bring a well-organized document.
- Similar knowledge under the same categories might be spread in different answers, pay attention to them, bring a well-organized document.
- Quality of the draft:
- The document is for understanding the source code, so you must keep mentioning names instead of using a too high-level abstraction language.
- You must use everything in `# DOCUMENT REQUEST`. Do not just make a summarize, `# DOCUMENT REQUEST` is already a summarize.
- You must use everything in `# DOCUMENT REQUEST`. Do not just make a summary, `# DOCUMENT REQUEST` is already a summary.
- Multiple levels of `#` markdown topic containing bullet points are favored.
## Steps for Improve
@@ -101,45 +101,3 @@
- The title of the document is in the `# DRAFT-TITLE` section.
- The content must be exactly and precisely the content under `# DRAFT-CONTENT`. But do not copy the `# DRAFT-CONTENT` title itself.
- Keep `Copilot_KB.md` unchanged.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Accessing Log Files and PowerShell Scripts
This guidance is for accessing following files mentioned in this instruction:
- `Copilot_Scrum.md`
- `Copilot_Task.md`
- `Copilot_Planning.md`
- `Copilot_Execution.md`
- `Copilot_KB.md`
- `copilotPrepare.ps1`
- `copilotBuild.ps1`
- `copilotExecute.ps1`
- `copilotDebug_Start.ps1`
- `copilotDebug_Stop.ps1`
- `copilotDebug_RunCommand.ps1`
- `Build.log`
- `Execute.log`
They are in the `REPO-ROOT/.github/TaskLogs` folder. `REPO-ROOT` is the root folder of the repo.
## If you are running in Visual Studio
You will find the `TaskLogs` project in the current solution, which should contain these files.
## Important Rules for Markdown Document or Log
- Do not print "````````" or "````````markdown" in markdown file.
- It is totally fine to have multiple top level `# Topic`.
- When mentioning a C++ name in markdown file:
- If it is defined in the standard C++ library or third-party library, use the full name.
- If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.

289
.github/prompts/win-4-execution.prompt.md vendored
View File

@@ -1,289 +0,0 @@
# Execution
- Checkout `Accessing Log Files and PowerShell Scripts` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should already be existing, you should not create any new files.
## Goal and Constraints
- You are going to apply changes to the source code following `Copilot_Execution.md`.
## Copilot_Execution.md Structure
- `# !!!EXECUTION!!!`: This file always begin with this title.
- `# UPDATES`:
- `## UPDATE`: There could be multiple occurrences. Each one has an exact copy of the update description I gave you.
- `# EXECUTION PLAN`.
- `# FIXING ATTEMPTS`.
## Step 1. Identify the Problem
- The execution document is in `Copilot_Execution.md`
- Find `# Update` in the LATEST chat message.
- Ignore any these titles in the chat history.
### Execute the Plan (only when no title appears in the LATEST chat message)
Ignore this section if there is any title in the LATEST chat message
I am starting a fresh new request.
- Apply all code changes in `Copilot_Execution.md` to the source code.
- Make sure indentation and line breaks are applied correctly, following the same style in the target file.
- After applying each step in `Copilot_Execution.md`, mark the step as completed by appending `[DONE]` after the step title. This allow you to find where you are if you are interrupted.
### Update the Source Code and Document (only when "# Update" appears in the LATEST chat message)
Ignore this section if there is no "# Update" in the LATEST chat message
I am going to propose some change to the source code.
- Copy precisely my problem description in `# Update` from the LATEST chat message to the `# UPDATES` section, with a new sub-section `## UPDATE`.
- Follow my update to change the source code.
- Update the document to keep it consistent with the source code.
## Step 2. Make Sure the Code Compiles but DO NOT Run Unit Test
- Check out `Compile the Solution` for details about compiling the solution but DO NOT run unit test.
- `Compile the Solution` is the only way to build the project. DO NOT call any other tools or scripts.
- Each attempt of build-fix process should be executed in a sub agent.
- One build-fix process includes one attempt following `Build Unit Test` and `Fix Compile Errors`.
- The main agent should call different sub agent for each build-fix process.
- Do not build and retrieve build results in the main agent.
### Use a sub agent to run the following instructions (`Build Unit Test` and `Fix Compile Errors`)
#### Build Unit Test
- Find out if there is any warning or error.
- `Compile the Solution` has the instruction about how to check compile result.
#### Fix Compile Errors
- If there is any compilation error, address all of them:
- If there is any compile warning, only fix warnings that caused by your code change. Do no fix any other warnings.
- If there is any compile error, you need to carefully identify, is the issue in the callee side or the caller side. Check out similar code before making a decision.
- For every attempt of fixing the source code:
- Explain why the original change did not work.
- Explain what you need to do.
- Explain why you think it would solve the build break.
- Log these in `Copilot_Execution.md`, with section `## Fixing attempt No.<attempt_number>` in `# FIXING ATTEMPTS`.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Make Sure the Code Compiles but DO NOT Run Unit Test`.
- When the code compiles:
- DO NOT run any tests, the code will be verified in future tasks.
# Step 3. Verify Coding Style
- Code changes in `Copilot_Execution.md` may not consider about indentation and coding style.
- Go over each code change and ensure:
- Indentation is correct and consistent with the surrounding code.
- Coding style especially line breaks follows the same conventions as the surrounding code.
- Ensure any empty line does not contain spaces or tabs.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Accessing Log Files and PowerShell Scripts
This guidance is for accessing following files mentioned in this instruction:
- `Copilot_Scrum.md`
- `Copilot_Task.md`
- `Copilot_Planning.md`
- `Copilot_Execution.md`
- `Copilot_KB.md`
- `copilotPrepare.ps1`
- `copilotBuild.ps1`
- `copilotExecute.ps1`
- `copilotDebug_Start.ps1`
- `copilotDebug_Stop.ps1`
- `copilotDebug_RunCommand.ps1`
- `Build.log`
- `Execute.log`
They are in the `REPO-ROOT/.github/TaskLogs` folder. `REPO-ROOT` is the root folder of the repo.
## If you are running in Visual Studio
You will find the `TaskLogs` project in the current solution, which should contain these files.
## Important Rules for Markdown Document or Log
- Do not print "````````" or "````````markdown" in markdown file.
- It is totally fine to have multiple top level `# Topic`.
- When mentioning a C++ name in markdown file:
- If it is defined in the standard C++ library or third-party library, use the full name.
- If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.
# Unit Test Projects to Work with
## Compile the Solution
- Run the `Build Unit Tests` task.
- DO NOT use msbuild by yourself.
### The Correct Way to Read Compiler Result
- The only source of trust is the raw output of the compiler.
- It is saved to `REPO-ROOT/.github/TaskLogs/Build.log`. `REPO-ROOT` is the root folder of the repo.
- Wait for the task to finish before reading the log file. DO NOT HURRY.
- 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 will show the following 3 lines, otherwise there are either warnings or errors. You can check the last 10 lines to make sure if build succceeded:
- "Build succeeded."
- "0 Warning(s)"
- "0 Error(s)"
- DO NOT TRUST related tools Visual Studio Code offers you, like `get_errors` or `get_task_output`, etc.
## Executing Unit Test
- Run the `Run Unit Tests` task.
- DO NOT call executables or scripts yourself.
### The Correct Way to Read Test Result
- The only source of trust is the raw output of the unit test process.
- It is saved to `REPO-ROOT/.github/TaskLogs/Execute.log`. `REPO-ROOT` is the root folder of the repo.
- Wait for the task to finish before reading the log file. DO NOT HURRY.
- 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.
- When all test case passes, the last several lines will show the following 2 lines, otherwise it crashed at the last showing test case. You can check the last 5 lines to make sure if all test cases passed:
- "Passed test files: X/X"
- "Passed test cases: Y/Y"
- DO NOT TRUST related tools Visual Studio Code offers you, like `get_errors` or `get_task_output`, etc.
## Debugging Unit Test
Debugging would be useful when you lack of necessary information.
In this section I offer you a set of powershell scripts that work with CDB (Microsoft's Console Debugger).
CDB accepts exactly same commands as WinDBG.
### Start a Debugger
`REPO-ROOT` is the root folder of the repo.
`SOLUTION-ROOT` is the folder of the solution (*.sln) file where the unit test project is in.
Find out `Unit Test Project Structure` 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/TaskLogs/Execute.log`.
Execute the following powershell commands:
```
cd SOLUTION-ROOT
start powershell {& REPO-ROOT\.github\TaskLogs\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 break-points.
After you are prepared, send the `g` command to start running.
### Stop a Debugger
You must call this script do 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\TaskLogs\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\TaskLogs\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` 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 break-point 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 break-point 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 break-point(s).
- **p**: step over, aka execute the complete current line.
- **t**: step in, aka execute the currrent 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 formmating applies to the **dx** command,
when you want to see raw data instead of formatting printing,
use **dx (EXPRESSION),!**.
You can also use `dv -rX` to expand "X" levels of fields, the default option is `-r0` which only expand 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`.
## Understanding the Building Tools
**WARNING**: Information offered in this section is for background knowledge only.
You should always run `Build Unit Tests` and `Run Unit Tests` instead of running these scripts or calling msbuild or other executable by yourself.
Only when you cannot access tools offered by Visual Studio Code, scripts below are allowed to use.
`REPO-ROOT` is the root folder of the repo.
`SOLUTION-ROOT` is the folder containing the solution file.
`PROJECT-NAME` is the name of the project.
When verifying test projects on Windows, msbuild is used to build a solution (`*.sln`) file.
A solution contains many project (`*.vcxproj`) files, a project generates an executable (`*.exe`) file.
Before building, ensure the debugger has stopped, otherwise the running unit test process will cause a linking failure.
If there is any error message, it means the debugger is not alive, it is good.
```
& REPO-ROOT\.github\TaskLogs\copilotDebug_Stop.ps1
```
The `Build Unit Tests` task calls msbuild to build the only solution which contains all test cases.
Inside the task, it runs `copilotBuild.ps1`
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\TaskLogs\copilotBuild.ps1
```
The `Run Unit Tests` task runs all generated *.exe file for each *.vcxproj that is created for test cases.
To run test cases in `SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj`
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\TaskLogs\copilotExecute.ps1 -Executable PROJECT-NAME
```
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`.
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, unlited files are skipped.
But if the element exists but there is no `/F:FILE-NAME.cpp`, it executes all test files, non is skipped.
**IMPORTANT**:
ONLY WHEN test files you want to run is skipped, you can update the filter to activate it. 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 is either not existing or it is totally unrelated to the current task you are working.
If the current task does not work on that test file, but it tests closely related topic, you should better 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.
### Unit Test Project Structure
In this project, the only unit test solution is `REPO-ROOT\Test\UnitTest\UnitTest.sln` therefore `SOLUTION-ROOT` is `REPO-ROOT\Test\UnitTest`.
Here is the list of all unit test projects under this solution and they are executed in the following order:
- UnitTest

307
.github/prompts/win-5-verifying.prompt.md vendored
View File

@@ -1,307 +0,0 @@
# Verifying
- Checkout `Accessing Log Files and PowerShell Scripts` for context about mentioned `*.md` and `*.ps1` files.
- All `*.md` and `*.ps1` files should already be existing, you should not create any new files.
## Goal and Constraints
- All instructions in `Copilot_Execution.md` should have been applied to the source code, your goal is to test it.
- You must ensure the source code compiles.
- You must ensure all tests pass.
- Until the code compiles and all test cases pass. Ensure there is a `# !!!VERIFIED!!!` mark at the end of `Copilot_Execution.md`.
## Step 1. Check and Respect my Code Change
- If you spot any difference between `Copilot_Execution.md` and the source code:
- It means I edited them. I have my reason. DO NOT change the code to match `Copilot_Execution.md`.
- Write down every differences you spotted, make a `## User Update Spotted` section in the `# UPDATES` section in `Copilot_Execution.md`.
## Step 2. Compile
- Check out `Compile the Solution` for details about compiling the solution but DO NOT run unit test yet.
- `Compile the Solution` is the only way to build the project. DO NOT call any other tools or scripts.
- Each attempt of build-fix process should be executed in a sub agent.
- One build-fix process includes one attempt following `Build Unit Test` and `Fix Compile Errors`.
- The main agent should call different sub agent for each build-fix process.
- Do not build and retrieve build results in the main agent.
### Use a sub agent to run the following instructions (`Build Unit Test` and `Fix Compile Errors`)
#### Build Unit Test
- Find out if there is any warning or error.
- `Compile the Solution` has the instruction about how to check compile result.
#### Fix Compile Errors
- If there is any compilation error, address all of them:
- If there is any compile warning, only fix warnings that caused by your code change. Do no fix any other warnings.
- If there is any compile error, you need to carefully identify, is the issue in the callee side or the caller side. Check out similar code before making a decision.
- For every attempt of fixing the source code:
- Explain why the original change did not work.
- Explain what you need to do.
- Explain why you think it would solve the build break or test break.
- Log these in `Copilot_Execution.md`, with section `## Fixing attempt No.<attempt_number>` in `# FIXING ATTEMPTS`.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
## Step 3. Run Unit Test
- Check out `Executing Unit Test` for details about running unit test projects.
- `Executing Unit Test` is the only way to run the unit test. DO NOT call any other tools or scripts.
- Each attempt of test-fix process should be executed in a sub agent.
- One test-fix process includes one attempt following `Execute Unit Test` and `Fix Failed Test Cases`.
- The main agent should call different sub agent for each test-fix process.
- Do not test and retrieve test results in the main agent.
### Use a sub agent to run the following instructions (`Execute Unit Test`, `Identify the Cause of Failure` and `Fix Failed Test Cases`)
#### Execute Unit Test
- Run the unit test and see if they passed. If anything is good, you will only see test files and test cases that are executed.
- Make sure added test cases are actually executed.
- If any test case fails on a test assertion, the content of `TEST_ASSERT` or other macros will be printed to the output.
- If any test case crashes, the failed test case will be the last one printed. In this case, you might need to add logging to the code.
- In any test case, `TEST_PRINT` would help.
- In other source code, `vl::console::Console::WriteLine` would help. In `Vlpp` project, you should `#include` `Console.h`. In other projects, the `Console` class should just be available.
- When added logging are not longer necessary, you should remove all of them.
#### Identify the Cause of Failure
- You can refer to `Copilot_Task.md` and `Copilot_Planning.md` to understand the context, keep the target unchanged.
- Dig into related source code carefully, make your assumption about the root cause.
- `TEST_ASSERT` in test cases or `vl::console::Console::WriteLine` in the source code would help.
- They can make sure the expected code path is executed.
- They can print variable values after converting to strings.
- Debug the unit test directly to get accurate clues if you are not confident of the assumption
- Follow `Debugging Unit Test` to start a debugger and run WinDBG commands.
- From there you can set break-points, walk through code by lines, and inspect variables.
- You must stop the debugger after you finish debugging.
- When you have made a few guess but did not progress, you are recommended to debug the unit test directly.
- Break-points are very useful to ensure the expected code path is executed, and you can inspect variable values.
#### Fix Failed Test Cases
- Apply fixings to source files.
- DO NOT delete any test case.
- For every attempt of fixing the source code:
- Explain why the original change did not work.
- Explain what you need to do.
- Explain why you think it would solve the build break or test break.
- Log these in `Copilot_Execution.md`, with section `## Fixing attempt No.<attempt_number>` in `# FIXING ATTEMPTS`.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
- `Step 2. Compile` and `Step 3. Run Unit Test` are absolutely no problem. If you didn't see any progress, the only reason is that your change is not correct.
## Step 4. Check it Again
- Go back to `Step 2. Compile`, follow all instructions and all steps again.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Accessing Log Files and PowerShell Scripts
This guidance is for accessing following files mentioned in this instruction:
- `Copilot_Scrum.md`
- `Copilot_Task.md`
- `Copilot_Planning.md`
- `Copilot_Execution.md`
- `Copilot_KB.md`
- `copilotPrepare.ps1`
- `copilotBuild.ps1`
- `copilotExecute.ps1`
- `copilotDebug_Start.ps1`
- `copilotDebug_Stop.ps1`
- `copilotDebug_RunCommand.ps1`
- `Build.log`
- `Execute.log`
They are in the `REPO-ROOT/.github/TaskLogs` folder. `REPO-ROOT` is the root folder of the repo.
## If you are running in Visual Studio
You will find the `TaskLogs` project in the current solution, which should contain these files.
## Important Rules for Markdown Document or Log
- Do not print "````````" or "````````markdown" in markdown file.
- It is totally fine to have multiple top level `# Topic`.
- When mentioning a C++ name in markdown file:
- If it is defined in the standard C++ library or third-party library, use the full name.
- If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.
# Unit Test Projects to Work with
## Compile the Solution
- Run the `Build Unit Tests` task.
- DO NOT use msbuild by yourself.
### The Correct Way to Read Compiler Result
- The only source of trust is the raw output of the compiler.
- It is saved to `REPO-ROOT/.github/TaskLogs/Build.log`. `REPO-ROOT` is the root folder of the repo.
- Wait for the task to finish before reading the log file. DO NOT HURRY.
- 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 will show the following 3 lines, otherwise there are either warnings or errors. You can check the last 10 lines to make sure if build succceeded:
- "Build succeeded."
- "0 Warning(s)"
- "0 Error(s)"
- DO NOT TRUST related tools Visual Studio Code offers you, like `get_errors` or `get_task_output`, etc.
## Executing Unit Test
- Run the `Run Unit Tests` task.
- DO NOT call executables or scripts yourself.
### The Correct Way to Read Test Result
- The only source of trust is the raw output of the unit test process.
- It is saved to `REPO-ROOT/.github/TaskLogs/Execute.log`. `REPO-ROOT` is the root folder of the repo.
- Wait for the task to finish before reading the log file. DO NOT HURRY.
- 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.
- When all test case passes, the last several lines will show the following 2 lines, otherwise it crashed at the last showing test case. You can check the last 5 lines to make sure if all test cases passed:
- "Passed test files: X/X"
- "Passed test cases: Y/Y"
- DO NOT TRUST related tools Visual Studio Code offers you, like `get_errors` or `get_task_output`, etc.
## Debugging Unit Test
Debugging would be useful when you lack of necessary information.
In this section I offer you a set of powershell scripts that work with CDB (Microsoft's Console Debugger).
CDB accepts exactly same commands as WinDBG.
### Start a Debugger
`REPO-ROOT` is the root folder of the repo.
`SOLUTION-ROOT` is the folder of the solution (*.sln) file where the unit test project is in.
Find out `Unit Test Project Structure` 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/TaskLogs/Execute.log`.
Execute the following powershell commands:
```
cd SOLUTION-ROOT
start powershell {& REPO-ROOT\.github\TaskLogs\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 break-points.
After you are prepared, send the `g` command to start running.
### Stop a Debugger
You must call this script do 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\TaskLogs\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\TaskLogs\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` 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 break-point 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 break-point 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 break-point(s).
- **p**: step over, aka execute the complete current line.
- **t**: step in, aka execute the currrent 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 formmating applies to the **dx** command,
when you want to see raw data instead of formatting printing,
use **dx (EXPRESSION),!**.
You can also use `dv -rX` to expand "X" levels of fields, the default option is `-r0` which only expand 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`.
## Understanding the Building Tools
**WARNING**: Information offered in this section is for background knowledge only.
You should always run `Build Unit Tests` and `Run Unit Tests` instead of running these scripts or calling msbuild or other executable by yourself.
Only when you cannot access tools offered by Visual Studio Code, scripts below are allowed to use.
`REPO-ROOT` is the root folder of the repo.
`SOLUTION-ROOT` is the folder containing the solution file.
`PROJECT-NAME` is the name of the project.
When verifying test projects on Windows, msbuild is used to build a solution (`*.sln`) file.
A solution contains many project (`*.vcxproj`) files, a project generates an executable (`*.exe`) file.
Before building, ensure the debugger has stopped, otherwise the running unit test process will cause a linking failure.
If there is any error message, it means the debugger is not alive, it is good.
```
& REPO-ROOT\.github\TaskLogs\copilotDebug_Stop.ps1
```
The `Build Unit Tests` task calls msbuild to build the only solution which contains all test cases.
Inside the task, it runs `copilotBuild.ps1`
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\TaskLogs\copilotBuild.ps1
```
The `Run Unit Tests` task runs all generated *.exe file for each *.vcxproj that is created for test cases.
To run test cases in `SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj`
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\TaskLogs\copilotExecute.ps1 -Executable PROJECT-NAME
```
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`.
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, unlited files are skipped.
But if the element exists but there is no `/F:FILE-NAME.cpp`, it executes all test files, non is skipped.
**IMPORTANT**:
ONLY WHEN test files you want to run is skipped, you can update the filter to activate it. 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 is either not existing or it is totally unrelated to the current task you are working.
If the current task does not work on that test file, but it tests closely related topic, you should better 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.
### Unit Test Project Structure
In this project, the only unit test solution is `REPO-ROOT\Test\UnitTest\UnitTest.sln` therefore `SOLUTION-ROOT` is `REPO-ROOT\Test\UnitTest`.
Here is the list of all unit test projects under this solution and they are executed in the following order:
- UnitTest

17
.github/prompts/win-ask.prompt.md vendored
View File

@@ -1,17 +0,0 @@
# Analysis
- This is analysis work, DO NOT update any source code.
- Find out the `Accessing the Knowledge Base` section. Understand the organization of the knowledge base.
- You are in a large C++ project, you must try your best to read any source code that may possibly related to the analysis work.
- Follow the chat message, try your best to answer an analysis work.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.

258
.github/prompts/win-code.prompt.md vendored
View File

@@ -1,258 +0,0 @@
# Task
## Goal and Constraints
- You must ensure the source code compiles.
- You must ensure all tests pass.
## Step 1. Implement Request
- Follow the chat message to implement the task.
## Step 2. Compile
- Check out `Compile the Solution` for details about compiling the solution but DO NOT run unit test yet.
- `Compile the Solution` is the only way to build the project. DO NOT call any other tools or scripts.
- Each attempt of build-fix process should be executed in a sub agent.
- One build-fix process includes one attempt following `Build Unit Test` and `Fix Compile Errors`.
- The main agent should call different sub agent for each build-fix process.
- Do not build and retrieve build results in the main agent.
### Use a sub agent to run the following instructions (`Build Unit Test` and `Fix Compile Errors`)
#### Build Unit Test
- Find out if there is any warning or error.
- `Compile the Solution` has the instruction about how to check compile result.
#### Fix Compile Errors
- If there is any compilation error, address all of them:
- If there is any compile warning, only fix warnings that caused by your code change. Do no fix any other warnings.
- If there is any compile error, you need to carefully identify, is the issue in the callee side or the caller side. Check out similar code before making a decision.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
## Step 3. Run Unit Test
- Check out `Executing Unit Test` for details about running unit test projects.
- `Executing Unit Test` is the only way to run the unit test. DO NOT call any other tools or scripts.
- Each attempt of test-fix process should be executed in a sub agent.
- One test-fix process includes one attempt following `Execute Unit Test` and `Fix Failed Test Cases`.
- The main agent should call different sub agent for each test-fix process.
- Do not test and retrieve test results in the main agent.
### Use a sub agent to run the following instructions (`Execute Unit Test`, `Identify the Cause of Failure` and `Fix Failed Test Cases`)
#### Execute Unit Test
- Run the unit test and see if they passed. If anything is good, you will only see test files and test cases that are executed.
- Make sure added test cases are actually executed.
- If any test case fails on a test assertion, the content of `TEST_ASSERT` or other macros will be printed to the output.
- If any test case crashes, the failed test case will be the last one printed. In this case, you might need to add logging to the code.
- In any test case, `TEST_PRINT` would help.
- In other source code, `vl::console::Console::WriteLine` would help. In `Vlpp` project, you should `#include` `Console.h`. In other projects, the `Console` class should just be available.
- When added logging are not longer necessary, you should remove all of them.
#### Identify the Cause of Failure
- Dig into related source code carefully, make your assumption about the root cause.
- `TEST_ASSERT` in test cases or `vl::console::Console::WriteLine` in the source code would help.
- They can make sure the expected code path is executed.
- They can print variable values after converting to strings.
- Debug the unit test directly to get accurate clues if you are not confident of the assumption
- Follow `Debugging Unit Test` to start a debugger and run WinDBG commands.
- From there you can set break-points, walk through code by lines, and inspect variables.
- You must stop the debugger after you finish debugging.
- When you have made a few guess but did not progress, you are recommended to debug the unit test directly.
- Break-points are very useful to ensure the expected code path is executed, and you can inspect variable values.
#### Fix Failed Test Cases
- Apply fixings to source files.
- DO NOT delete any test case.
- After finishing fixing, exit the current sub agent and tell the main agent to go back to `Step 2. Compile`
- `Step 2. Compile` and `Step 3. Run Unit Test` are absolutely no problem. If you didn't see any progress, the only reason is that your change is not correct.
## Step 4. Check it Again
- Go back to `Step 2. Compile`, follow all instructions and all steps again.
# External Tools Environment and Context
- You are on Windows running in Visual Studio Code.
- Submitting CLI commands is not recommended unless you have no choice.
- There is some rules to follow to submit correct powershell commands:
- DO NOT call `msbuild` or other executable files by yourself.
- DO NOT create or delete any file unless explicitly directed.
- MUST run any powershell script in this format: `& absolute-path.ps1 parameters...`.
- MUST run tasks via Cursor for compiling and running test cases.
# Unit Test Projects to Work with
## Compile the Solution
- Run the `Build Unit Tests` task.
- DO NOT use msbuild by yourself.
### The Correct Way to Read Compiler Result
- The only source of trust is the raw output of the compiler.
- It is saved to `REPO-ROOT/.github/TaskLogs/Build.log`. `REPO-ROOT` is the root folder of the repo.
- Wait for the task to finish before reading the log file. DO NOT HURRY.
- 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 will show the following 3 lines, otherwise there are either warnings or errors. You can check the last 10 lines to make sure if build succceeded:
- "Build succeeded."
- "0 Warning(s)"
- "0 Error(s)"
- DO NOT TRUST related tools Visual Studio Code offers you, like `get_errors` or `get_task_output`, etc.
## Executing Unit Test
- Run the `Run Unit Tests` task.
- DO NOT call executables or scripts yourself.
### The Correct Way to Read Test Result
- The only source of trust is the raw output of the unit test process.
- It is saved to `REPO-ROOT/.github/TaskLogs/Execute.log`. `REPO-ROOT` is the root folder of the repo.
- Wait for the task to finish before reading the log file. DO NOT HURRY.
- 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.
- When all test case passes, the last several lines will show the following 2 lines, otherwise it crashed at the last showing test case. You can check the last 5 lines to make sure if all test cases passed:
- "Passed test files: X/X"
- "Passed test cases: Y/Y"
- DO NOT TRUST related tools Visual Studio Code offers you, like `get_errors` or `get_task_output`, etc.
## Debugging Unit Test
Debugging would be useful when you lack of necessary information.
In this section I offer you a set of powershell scripts that work with CDB (Microsoft's Console Debugger).
CDB accepts exactly same commands as WinDBG.
### Start a Debugger
`REPO-ROOT` is the root folder of the repo.
`SOLUTION-ROOT` is the folder of the solution (*.sln) file where the unit test project is in.
Find out `Unit Test Project Structure` 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/TaskLogs/Execute.log`.
Execute the following powershell commands:
```
cd SOLUTION-ROOT
start powershell {& REPO-ROOT\.github\TaskLogs\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 break-points.
After you are prepared, send the `g` command to start running.
### Stop a Debugger
You must call this script do 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\TaskLogs\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\TaskLogs\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` 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 break-point 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 break-point 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 break-point(s).
- **p**: step over, aka execute the complete current line.
- **t**: step in, aka execute the currrent 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 formmating applies to the **dx** command,
when you want to see raw data instead of formatting printing,
use **dx (EXPRESSION),!**.
You can also use `dv -rX` to expand "X" levels of fields, the default option is `-r0` which only expand 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`.
## Understanding the Building Tools
**WARNING**: Information offered in this section is for background knowledge only.
You should always run `Build Unit Tests` and `Run Unit Tests` instead of running these scripts or calling msbuild or other executable by yourself.
Only when you cannot access tools offered by Visual Studio Code, scripts below are allowed to use.
`REPO-ROOT` is the root folder of the repo.
`SOLUTION-ROOT` is the folder containing the solution file.
`PROJECT-NAME` is the name of the project.
When verifying test projects on Windows, msbuild is used to build a solution (`*.sln`) file.
A solution contains many project (`*.vcxproj`) files, a project generates an executable (`*.exe`) file.
Before building, ensure the debugger has stopped, otherwise the running unit test process will cause a linking failure.
If there is any error message, it means the debugger is not alive, it is good.
```
& REPO-ROOT\.github\TaskLogs\copilotDebug_Stop.ps1
```
The `Build Unit Tests` task calls msbuild to build the only solution which contains all test cases.
Inside the task, it runs `copilotBuild.ps1`
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\TaskLogs\copilotBuild.ps1
```
The `Run Unit Tests` task runs all generated *.exe file for each *.vcxproj that is created for test cases.
To run test cases in `SOLUTION-ROOT\PROJECT-NAME\PROJECT-NAME.vcxproj`
```
cd SOLUTION-ROOT
& REPO-ROOT\.github\TaskLogs\copilotExecute.ps1 -Executable PROJECT-NAME
```
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`.
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, unlited files are skipped.
But if the element exists but there is no `/F:FILE-NAME.cpp`, it executes all test files, non is skipped.
**IMPORTANT**:
ONLY WHEN test files you want to run is skipped, you can update the filter to activate it. 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 is either not existing or it is totally unrelated to the current task you are working.
If the current task does not work on that test file, but it tests closely related topic, you should better 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.
### Unit Test Project Structure
In this project, the only unit test solution is `REPO-ROOT\Test\UnitTest\UnitTest.sln` therefore `SOLUTION-ROOT` is `REPO-ROOT\Test\UnitTest`.
Here is the list of all unit test projects under this solution and they are executed in the following order:
- UnitTest