diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c8c6a7a3dc..08958f64fa 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,12 +4,7 @@ This is the source repository for **Windows Terminal**, **Windows Console Host** ## Build -Requires Visual Studio 2022 (17.10+) with "Desktop Development with C++" and "Universal Windows Platform Development" workloads, plus the Windows 11 SDK (10.0.22621.0). The solution uses the `.slnx` format (`OpenConsole.slnx`), which requires MSBuild 17.10 or later. If you get `"Invalid input 'OpenConsole.slnx'. The file type was not recognized."`, update Visual Studio. - -```powershell -# First time: initialize submodules -git submodule update --init --recursive -``` +Requires Visual Studio (preferably Visual Studio 2026) with "Desktop Development with C++" and "Universal Windows Platform Development" workloads, plus the Windows 11 SDK (10.0.22621.0). The solution uses the `.slnx` format (`OpenConsole.slnx`), which requires MSBuild 17.10 or later. If you get `"Invalid input 'OpenConsole.slnx'. The file type was not recognized."`, update Visual Studio. Build uses MSBuild via the CMD razzle environment. Run `razzle.cmd` once per terminal session to set up the environment, then use the build commands. Since razzle sets env vars in CMD, chain commands with `&&` when calling from PowerShell (e.g., `cmd /c ".\tools\razzle.cmd && bz"`): diff --git a/README.md b/README.md index 348424385f..ad97676952 100644 --- a/README.md +++ b/README.md @@ -257,6 +257,9 @@ We are excited to work alongside you, our amazing community, to build and enhanc **Before you start work on a feature/fix**, please read & follow the [Windows Terminal Contributor's Guide](https://github.com/microsoft/terminal/blob/main/CONTRIBUTING.md). The contribution process is the same. +For local dev/build of this repo, see: +[quick-start-local-dev](doc/quick-start-local-dev.md) + --- ## Code of Conduct diff --git a/doc/building.md b/doc/building.md index af1c7e7510..6b3e017f05 100644 --- a/doc/building.md +++ b/doc/building.md @@ -1,11 +1,7 @@ # How to build OpenConsole -This repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for some of its dependencies. To make sure submodules are restored or updated, be sure to run the following prior to building: - -```shell -git submodule update --init --recursive -``` +This repository's dependencies come from NuGet, vcpkg, and the vendored `oss/` tree, and are restored automatically by the build. OpenConsole.slnx may be built from within Visual Studio or from the command-line using a set of convenience scripts & tools in the **/tools** directory: diff --git a/doc/quick-start-local-dev.md b/doc/quick-start-local-dev.md new file mode 100644 index 0000000000..b510f560bd --- /dev/null +++ b/doc/quick-start-local-dev.md @@ -0,0 +1,63 @@ +# Quick start for local development + + +The fast path for local development. Intelligent Terminal is a dual-stack project: the Rust +**WTA** agent (`tools/wta/`) plus the C++ **Windows Terminal** app (`src/`). For command-line +builds, CI, packaging, and troubleshooting, see [building.md](./building.md). + +## 1. First-time setup + +**1.1. Install:** + +- **Visual Studio 2026 (18.x)** with the **Desktop development with C++** and **Universal Windows + Platform development** workloads. +- **Rust** via [rustup](https://rustup.rs/) (standard rustup; the repo's toolchain pin falls back + to stable). + +Then open `OpenConsole.slnx` in Visual Studio and click **Install** on the "extra components" +prompt. It reads `.vsconfig` and adds what the build needs, including **C++ Universal Windows +Platform tools (Latest MSVC)** (required for `WindowsTerminal` to load; a separate item from the +UWP workload). NuGet and vcpkg dependencies restore automatically during the build, so that is all +the setup needed. + +**1.2. Build and run** (two build systems, in order): + +1. Build the Rust agent: + `cargo build --target --manifest-path ` + + For instance, + ```powershell + cargo build --target x86_64-pc-windows-msvc --manifest-path tools/wta/Cargo.toml + ``` +2. In Visual Studio: + - Set startup project: **`CascadiaPackage`** + - Select platform, **x64** for instance. + - Go to `CascadiaPackage` > Properties > Debug: set **Application process** and **Background task + process** to **Native Only** + - Run (**F5**) + +F5 builds the app, deploys, and launches Windows Terminal (Dev) with the debugger attached. The +first build is slow; later ones are incremental. + +## 2. After changing code + +| Changed | Do this | +|---------|---------| +| **Rust** (`tools/wta/`) | Rebuild via `cargo build`. For instance,
`cargo build --target x86_64-pc-windows-msvc --manifest-path tools/wta/Cargo.toml` | +| **C++** (`src/`) | Press **F5** in Visual Studio | + +`cargo build` is incremental (seconds for a small change). To see a WTA change inside the running +Terminal (agent pane, autofix), press **F5** afterward so the new `wta.exe` is copied in. + +> If a rebuild reports `wta.exe` in use, stop the running instance first: close the Dev Terminal, +> or run `taskkill /f /im wta.exe`. + +## 3. Running tests + +| Side | Command | +|------|---------| +| **Rust** | `cargo test --manifest-path tools/wta/Cargo.toml` | +| **C++** (TAEF) | `runut.cmd` (unit), `runft.cmd` (feature), `runuia.cmd` (UIA), from a dev environment | + +Run one C++ test with `te.exe /name:`. See [building.md](./building.md) for +the dev environment and [TAEF.md](./TAEF.md) for details. diff --git a/tools/razzle.cmd b/tools/razzle.cmd index 51d0ec8f1f..f84c32620e 100644 --- a/tools/razzle.cmd +++ b/tools/razzle.cmd @@ -30,7 +30,7 @@ set MSBUILD= rem GH#1313: If msbuild is already on the path, we don't need to look for it. for %%X in (msbuild.exe) do (set MSBUILD=%%~$PATH:X) if defined MSBUILD ( - echo Using MsBuild at %MSBUILD% which was already on the path. + echo Using MSBuild at %MSBUILD% which was already on the path. goto :FOUND_MSBUILD ) @@ -44,29 +44,42 @@ for /f "usebackq delims=" %%I in (`dir /b /aD /o-N /s "%~dp0..\packages\vswhere* if not defined VSWHERE ( echo Could not find vswhere on your machine. Please set the VSWHERE variable to the location of vswhere.exe and run razzle again. - goto :EXIT + exit /b 1 ) rem Add path to MSBuild Binaries rem -rem We're going to always prefer prerelease version of VS 2022. The -version -rem range [17.0,18.0) ensures we pick VS 2022 (including previews) but not a -rem newer major version whose toolset may be incompatible with our v143 -rem PlatformToolset. If you need VS 18+, update PlatformToolset in -rem src\common.build.pre.props as well. +rem We accept the latest prerelease of VS in the 17.x or 18.x range. The -version +rem range [17.0,19.0) picks up both VS 2022 (17.x) and VS 18 (including previews) +rem but not a still-newer major whose toolset may be incompatible. VS 18 uses our +rem v145 PlatformToolset (see src\common.build.pre.props); older VS versions default +rem to v143. rem -for /f "usebackq tokens=*" %%B in (`%VSWHERE% -latest -prerelease -products * -requires Microsoft.Component.MSBuild -version "[17.0,18.0)" -find MSBuild\**\Bin\MSBuild.exe 2^>nul`) do ( +for /f "usebackq tokens=*" %%B in (`"%VSWHERE%" -latest -prerelease -products * -requires Microsoft.Component.MSBuild -version "[17.0,19.0)" -find MSBuild\**\Bin\MSBuild.exe 2^>nul`) do ( set MSBUILD=%%B ) if not defined MSBUILD ( - echo Could not find MsBuild on your machine. Please set the MSBUILD variable to the location of MSBuild.exe and run razzle again. - goto :EXIT + echo Could not find MSBuild on your machine. Please set the MSBUILD variable to the location of MSBuild.exe and run razzle again. + exit /b 1 ) :FOUND_MSBUILD -set PATH=%PATH%%MSBUILD%\..; +rem Guard: make sure we actually resolved a real MSBuild.exe. Without this, a +rem chained command like `razzle && bcz` would run bcz with an empty MSBUILD/ +rem PLATFORM/CONFIGURATION and fail cryptically with '""' is not recognized. +if not exist "%MSBUILD%" ( + echo Could not find a usable MSBuild.exe ^(resolved: "%MSBUILD%"^). + echo Open a "Developer PowerShell/Command Prompt for VS", or run + echo Import-Module .\tools\OpenConsole.psm1; Set-MsbuildDevEnvironment + echo in your shell before razzle, then try again. + exit /b 1 +) + +rem Add MSBuild's own directory to PATH, with a proper ; separator. +for %%F in ("%MSBUILD%") do set "MSBUILD_BIN=%%~dpF" +set "PATH=%PATH%;%MSBUILD_BIN%" if "%PROCESSOR_ARCHITECTURE%" == "AMD64" ( set ARCH=x64 @@ -123,5 +136,4 @@ set OpenConBuild=true :END echo The dev environment is ready to go! - -:EXIT +exit /b 0