mirror of
https://github.com/vczh-libraries/Release.git
synced 2026-03-23 07:42:52 +08:00
164 lines
10 KiB
Markdown
164 lines
10 KiB
Markdown
# General Instruction
|
|
|
|
- `REPO-ROOT` refers to the root directory of the repository.
|
|
- `SOLUTION-ROOT` refers to the root directory of a solution (`*.sln` or `*.slnx`).
|
|
- Solutions and projects you need to work on could be found in `REPO-ROOT/Project.md`.
|
|
- Following `Leveraging the Knowledge Base`, find knowledge and documents for this project in `REPO-ROOT/.github/KnowledgeBase/Index.md`.
|
|
- Before writing to a source file, read it again and make sure you respect my parallel editing.
|
|
- If any `*.prompt.md` file is referenced, take immediate action following the instructions in that file.
|
|
|
|
## External Tools Environment and Context
|
|
|
|
- If you are on Windows OS:
|
|
- Always prefer the offered script files instead of direct CLI commands.
|
|
- DO NOT call `msbuild` or other executable files directly.
|
|
- DO NOT create or delete any file unless explicitly directed.
|
|
- MUST run any PowerShell script in this format: `& absolute-path.ps1 parameters...`.
|
|
- Multiple powershell commands are concatenated with `;` to be executed in one line.
|
|
|
|
- If you are on Linux, offered powershell script files won't work and here are replacements:
|
|
- You still need to maintain `*.sln`, `*.slnx`, `*.vcxitems`, `*.vcxproj`, `*.vcxproj.filters`.
|
|
- DO NOT call `cmake` (as cmake is not in use), `make`, `clang++`, `g++`.
|
|
- DO NOT call `gdb` or `lldb` unless you can interact with it, otherwise a running debugger will cause subsequent building to fail.
|
|
- All `makefile` files are generated out of these solution and project files.
|
|
- All `vmake` files are in `REPO-ROOT/Test/Linux` or its sub folders.
|
|
- If `vmake` is directly in that folder, that is the only project you can and need to work on.
|
|
- Otherwise, any important `*.vcxproj` will have a corresponding folder containing the `vmake` for that project.
|
|
- DO NOT modify `makefile` as they will be re-generated and your modification will be lost. Modify `vmake` instead. In `vmake` you can:
|
|
- Add a `*.vcxitems` or `*.vcxproj` project to add every file they use
|
|
- Remove C++ source files added from projects that only work for Windows
|
|
- Add new C++ source files for Linux replacement, etc.
|
|
- All following commands should run in the folder containing the `vmake` file:
|
|
- `vmake --make` to generate `makefile` according to the latest content in solution and project files.
|
|
- `vbuild --build` to incrementally build the project.
|
|
- `vbuild --full-build` to fully rebuild the project.
|
|
- An executable file `./Bin/UnitTest` is generated after a successful `vbuild`.
|
|
|
|
## Coding Guidelines and Tools
|
|
|
|
The C++ project in this repo is built and tested using its own msbuild wrappers.
|
|
You must strictly follow the instructions in the following documents,
|
|
otherwise it won't work properly.
|
|
|
|
- Adding/Removing/Renaming Source Files: `REPO-ROOT/.github/Guidelines/SourceFileManagement.md`
|
|
- Building a Solution: `REPO-ROOT/.github/Guidelines/Building.md`
|
|
- Running a Project:
|
|
- Unit Test: `REPO-ROOT/.github/Guidelines/Running-UnitTest.md`
|
|
- CLI Application: `REPO-ROOT/.github/Guidelines/Running-CLI.md`
|
|
- GacUI Application: `REPO-ROOT/.github/Guidelines/Running-GacUI.md` (to edit ...)
|
|
- Debugging a Project: `REPO-ROOT/.github/Guidelines/Debugging.md`
|
|
- Using Unit Test Framework: `REPO-ROOT/.github/KnowledgeBase/manual/unittest/vlpp.md`
|
|
- Using Unit Test Framework for GacUI Application:
|
|
- Running GacUI in Unit Test Framework: `REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui.md`
|
|
- Snapshots and Frames: `REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_frame.md`
|
|
- IO Interaction: `REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_io.md`
|
|
- Accessing: `REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_controls.md`
|
|
- Snapshot Viewer: `REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_snapshots.md`
|
|
- Syntax of GacUI XML Resources:
|
|
- Brief Introduction: `REPO-ROOT/.github/Guidelines/GacUIXmlResource.md`
|
|
- Detailed document can be found in `REPO-ROOT/.github/KnowledgeBase/Index.md` under `# Copy of Online Manual` / `## GacUI`, in the `GacUI XML Resource` item and all sub items.
|
|
- Syntax of Workflow Script (the script language in GacUI XML Resource):
|
|
- Detailed document can be found in `REPO-ROOT/.github/KnowledgeBase/Index.md` under `# Copy of Online Manual` / `## Workflow Script`, in the `Syntax` item and all sub items.
|
|
|
|
## Accessing Task Documents
|
|
|
|
If you need to find any document for the current working task, they are in the `REPO-ROOT/.github/TaskLogs` folder:
|
|
- `Copilot_Scrum.md`
|
|
- `Copilot_Task.md`
|
|
- `Copilot_Planning.md`
|
|
- `Copilot_Execution.md`
|
|
- `Copilot_KB.md`
|
|
- `Copilot_Investigate.md`
|
|
|
|
### Important Rules for Writing Markdown Files
|
|
|
|
- Do not print "````````" or "````````markdown" in a 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.
|
|
|
|
## Accessing Script Files
|
|
|
|
If you need to find any script or log files, they are in the `REPO-ROOT/.github/Scripts` folder:
|
|
- `copilotPrepare.ps1`
|
|
- `copilotPrepareReview.ps1`
|
|
- `copilotBuild.ps1`
|
|
- `copilotExecute.ps1`
|
|
- `copilotDebug_Start.ps1`
|
|
- `copilotDebug_Stop.ps1`
|
|
- `copilotDebug_RunCommand.ps1`
|
|
- `Build.log`
|
|
- `Execute.log`
|
|
|
|
## Writing C++ Code
|
|
|
|
- This project uses C++ 20, you are recommended to use new C++ 20 feature aggressively.
|
|
- All code should be cross-platform. In case when an OS feature is needed, a Windows version and a Linux version should be prepared in different files, following the `*.Windows.cpp` and `*.Linux.cpp` naming convention, and keep them as small as possible.
|
|
- DO NOT MODIFY any source code in the `Import` folder, they are dependencies.
|
|
- DO NOT MODIFY any source code in the `Release` folder, they are generated release files.
|
|
- You can modify source code in the `Source` and `Test` folder.
|
|
- Use tabs for indentation in C++ source code.
|
|
- Use double spaces for indentation for JSON or XML embedded in C++ source code.
|
|
- Use `auto` to define variables if it is doable. Use `auto&&` when the type is big or when it is a collection type.
|
|
- The project only uses a very minimal subset of the standard library. I have substitutions for most of the STL constructions. Always use mine if possible:
|
|
- Always use `vint` instead of `int`.
|
|
- Always use `L'x'`, `L"x"`, `wchar_t`, `const wchar_t` and `vl::WString`, instead of `std::string` or `std::wstring`.
|
|
- Use my own collection types vl::collections::* instead of std::*
|
|
- Regular expression utilities are offered by `vl::regex::Regex`, here are important syntax differences with other regular expression implementation:
|
|
- "." means the dot character, "/." or "\." (or "\\." in C++ string literal) means any character.
|
|
- Both "/" and "\" escape characters, you are recommended to use "/" in C++ string literals.
|
|
- Therefore you need "//" for the "/" character and "/\\" or "/\\\\" for the "\" character in C++ string literals.
|
|
- Check out `REPO-ROOT/.github/KnowledgeBase/Index.md` for more information of how to choose correct C++ data types.
|
|
- Rules for C++ header files:
|
|
- Guard them with macros instead of `#pragma once`.
|
|
- In a class/struct/union declaration, member names must be aligned in the same column at least in the same public, protected or private section.
|
|
- Keep the coding style consistent with other header files in the same project.
|
|
- Extra Rules for C++ header files in `Source` folder:
|
|
- Do not use `using namespace` statement, full name of types are always required.
|
|
- Rules for cpp files:
|
|
- Use `using namespace` statement if necessary to prevent from repeating namespace everywhere.
|
|
- `vl::stream::` is an exception, always use `stream::` with `using namespace vl;`, DO NOT use `using namespace vl::stream;`.
|
|
|
|
## Leveraging the Knowledge Base
|
|
|
|
- When making design or coding decisions, you must leverage the knowledge base to make the best choice.
|
|
- The main entry is `REPO-ROOT/.github/KnowledgeBase/Index.md`, it is organized in this way:
|
|
- `## Guidance`: A general guidance that plays a super important part repo-wide.
|
|
- Each `## Project`: A brief description of each project and its purpose.
|
|
- `### Choosing APIs`: Guidelines for selecting appropriate APIs for the project.
|
|
- `### Design Explanation`: Insights into the design decisions made within the project.
|
|
- `## Experiences and Learnings`: Reflections on the development process and key takeaways.
|
|
- `# Copy of Online Manual`: A copy of the online manual so that you don't need network access. They are much more detailed, offering selectively important information.
|
|
- Each `## Project`: A copy of online manual for that project, organized in the same way as the knowledge base.
|
|
- Not every project is included.
|
|
- Manual for the unit test framework is in `## Unit Testing`.
|
|
|
|
### Project/Choosing APIs
|
|
|
|
There are multiple categories under `Choosing APIs`. Each category begins with a short and accurate title `#### Category`.
|
|
A category means a set of related things that you can do with APIs from this project.
|
|
|
|
Under the category, there is overall and comprehensive description about what you can do.
|
|
|
|
Under the description, there are bullet points and each item follow the format: `- Use CLASS-NAME for blahblahblah` (If a function does not belong to a class, you can generate `Use FUNCTION-NAME ...`).
|
|
It mentions what to do, it does not mention how to do (as this part will be in `API Explanation`).
|
|
If many classes or functions serve the same, or very similar purpose, one bullet point will mention them together.
|
|
|
|
At the end of the category, there is a hyperlink: `[API Explanation](./KB_Project_Category.md)` (no space between file name, all pascal case).
|
|
|
|
### Project/Design Explanation
|
|
|
|
There are multiple topics under `Design Explanation`. Each topic begins with a short and accurate title `#### Topic`.
|
|
A topic means a feature of this project, it will be multiple components combined.
|
|
|
|
Under the topic, there is overall and comprehensive description about what does this feature do.
|
|
|
|
Under the description, there are bullet points to provide a little more detail, but do not make it too long. Full details are supposed to be in the document from the hyperlink.
|
|
|
|
At the end of the topic, there is a hyperlink: `[Design Explanation](./KB_Project_Design_Topic.md)` (no space between file name, all pascal case).
|
|
|
|
### Experiences and Learnings
|
|
|
|
(to edit ...)
|