|
| 1 | +# Usage Guide |
| 2 | + |
| 3 | +**mcpp-standard** is a hands-on tutorial project focused on Modern C++ core language features. Based on the [xlings(d2x) tool](https://github.com/Sunrisepeak/mcpp-standard), it implements a **compiler-driven development model** for code practice that can automatically detect exercise code status and navigate to the next exercise. |
| 4 | + |
| 5 | +## 0. xlings Tool Installation |
| 6 | + |
| 7 | +> xlings contains the tools required for the tutorial project - [More tool details](https://github.com/d2learn/xlings) |
| 8 | +
|
| 9 | +**Linux** |
| 10 | + |
| 11 | +```bash |
| 12 | +curl -fsSL https://d2learn.org/xlings-install.sh | bash |
| 13 | +``` |
| 14 | + |
| 15 | +or |
| 16 | + |
| 17 | +```bash |
| 18 | +wget https://d2learn.org/xlings-install.sh -O - | bash |
| 19 | +``` |
| 20 | + |
| 21 | +**Windows - PowerShell** |
| 22 | + |
| 23 | +```bash |
| 24 | +Invoke-Expression (Invoke-Webrequest 'https://d2learn.org/xlings-install.ps1.txt' -UseBasicParsing).Content |
| 25 | +``` |
| 26 | + |
| 27 | +## 1. Get Project and Auto-configure Environment |
| 28 | + |
| 29 | +> Download the project to current directory and automatically configure local environment |
| 30 | +
|
| 31 | +```bash |
| 32 | +xlings install d2x:mcpp-standard |
| 33 | +``` |
| 34 | + |
| 35 | +### Local E-book |
| 36 | + |
| 37 | +> Execute `d2x book` command in the project directory to open local documentation (includes usage guide and e-book) |
| 38 | +
|
| 39 | +```bash |
| 40 | +d2x book |
| 41 | +``` |
| 42 | + |
| 43 | +### Practice Code Auto-detection |
| 44 | + |
| 45 | +> Enter the project directory `mcpp-standard` and run the checker command to enter the practice code auto-detection program |
| 46 | +
|
| 47 | +```bash |
| 48 | +xlings checker |
| 49 | +``` |
| 50 | + |
| 51 | +### Specify Exercise for Detection |
| 52 | + |
| 53 | +```bash |
| 54 | +xlings checker [name] |
| 55 | +``` |
| 56 | + |
| 57 | +> Note: Exercise names support fuzzy matching |
| 58 | +
|
| 59 | +### Sync Latest Practice Code |
| 60 | + |
| 61 | +> Since the project is continuously updated, you can use the following command for automatic synchronization (if synchronization fails, you may need to manually update the project code using git) |
| 62 | +
|
| 63 | +```bash |
| 64 | +d2x update |
| 65 | +``` |
| 66 | + |
| 67 | +## 2. Automated Detection Program Introduction |
| 68 | + |
| 69 | +After entering the automated code practice environment using `xlings checker`, the tool will automatically locate and open the corresponding practice code file, and output compiler errors and hints in the console. The detection program generally has two detection phases: the first is compile-time detection, where you need to fix compilation errors based on hints in the practice code and compiler error messages in the console; the second is runtime detection, which checks if the current code passes all checkpoints when running. When compilation errors are fixed and all checkpoints are passed, the console will display that the current exercise is completed and prompt you to proceed to the next exercise. |
| 70 | + |
| 71 | +**Practice Code File Example** |
| 72 | + |
| 73 | +```cpp |
| 74 | +// mcpp-standard: https://github.com/Sunrisepeak/mcpp-standard |
| 75 | +// license: Apache-2.0 |
| 76 | +// file: dslings/hello-mcpp.cpp |
| 77 | +// |
| 78 | +// Exercise: Automated Code Practice Tutorial |
| 79 | +// |
| 80 | +// Tips: |
| 81 | +// This project uses the xlings tool to build automated code practice projects. Execute |
| 82 | +// xlings checker in the project root directory to enter "compiler-driven development mode" |
| 83 | +// for automatic exercise code detection. |
| 84 | +// You need to modify errors in the code based on console error messages and hints. |
| 85 | +// When all compilation errors and runtime checkpoints are fixed, you can delete or comment |
| 86 | +// out the D2X_WAIT macro in the code to automatically proceed to the next exercise. |
| 87 | +// |
| 88 | +// - D2X_WAIT: This macro isolates different exercises. You can delete or comment it out to proceed to the next exercise. |
| 89 | +// - d2x_assert_eq: This macro is used for runtime checkpoints. You need to fix code errors so that all |
| 90 | +// - D2X_YOUR_ANSWER: This macro indicates code that needs modification, typically used for code completion (replace this macro with correct code) |
| 91 | +// |
| 92 | +// Auto-Checker Command: |
| 93 | +// |
| 94 | +// d2x checker hello-mcpp |
| 95 | +// |
| 96 | + |
| 97 | +#include <d2x/common.hpp> |
| 98 | + |
| 99 | +// You can observe "real-time" changes in the console when modifying code |
| 100 | + |
| 101 | +int main() { |
| 102 | + |
| 103 | + std::cout << "hello, mcpp!" << std:endl; // 0. Fix this compilation error |
| 104 | + |
| 105 | + int a = 1.1; // 1. Fix this runtime error, change int to double to pass the check |
| 106 | + |
| 107 | + d2x_assert_eq(a, 1.1); // 2. Runtime checkpoint, need to fix code to pass all checkpoints (cannot directly delete checkpoint code) |
| 108 | + |
| 109 | + D2X_YOUR_ANSWER b = a; // 3. Fix this compilation error, give b an appropriate type |
| 110 | + |
| 111 | + d2x_assert_eq(b, 1); // 4. Runtime checkpoint 2 |
| 112 | + |
| 113 | + D2X_WAIT // 5. Delete or comment out this macro to proceed to the next exercise (project formal code practice) |
| 114 | + |
| 115 | + return 0; |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +**Console Output and Explanation** |
| 120 | + |
| 121 | +```bash |
| 122 | +🌏Progress: [>----------] 0/10 -->> Shows current exercise progress |
| 123 | + |
| 124 | +[Target: 00-0-hello-mcpp] - normal -->> Current exercise name |
| 125 | + |
| 126 | +❌ Error: Compilation/Running failed for dslings/hello-mcpp.cpp -->> Shows detection status |
| 127 | + |
| 128 | + The code exist some error! |
| 129 | + |
| 130 | +---------C-Output--------- - Compiler output information |
| 131 | +[HONLY LOGW]: main: dslings/hello-mcpp.cpp:24 - ❌ | a == 1.1 (1 == 1.100000) -->> Error hint and location (line 24) |
| 132 | +[HONLY LOGW]: main: dslings/hello-mcpp.cpp:26 - 🥳 Delete the D2X_WAIT to continue... |
| 133 | + |
| 134 | + |
| 135 | +AI-Tips-Config: https://d2learn.org/docs/xlings -->> AI hints (requires configuring large model key, optional) |
| 136 | + |
| 137 | +---------E-Files--------- |
| 138 | +dslings/hello-mcpp.cpp -->> Current detected file |
| 139 | +------------------------- |
| 140 | + |
| 141 | +Homepage: https://github.com/d2learn/xlings |
| 142 | +``` |
| 143 | + |
| 144 | +## 3. Resources and Communication |
| 145 | + |
| 146 | +**Communication Group (Q):** 167535744 |
| 147 | + |
| 148 | +**Tutorial Discussion Section:** [https://forum.d2learn.org/category/20](https://forum.d2learn.org/category/20) |
| 149 | + |
| 150 | +**xlings:** [https://github.com/d2learn/xlings](https://github.com/d2learn/xlings) |
| 151 | + |
| 152 | +**Tutorial Repository:** [https://github.com/Sunrisepeak/mcpp-standard](https://github.com/Sunrisepeak/mcpp-standard) |
| 153 | + |
| 154 | +**Tutorial Video Collection:** [https://space.bilibili.com/65858958/lists/5208246](https://space.bilibili.com/65858958/lists/5208246) |
0 commit comments