### Build and Install Scalar on Mac Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md These bash scripts are used to build and install Scalar on macOS. Navigate to the Scripts/Mac directory and execute the build script, followed by the install script from the output directory. ```bash cd Scripts/Mac ./BuildScalarForMac.sh cd ../../../out/Scalar.Installer.Mac/dist/(Debug|Release)/ ./InstallScalar.sh ``` -------------------------------- ### Platform-Specific Installation/Update Commands Source: https://github.com/microsoft/scalar/blob/main/Readme.md Commands and procedures for updating Scalar installations on Windows, macOS, and Linux, including uninstallation of older versions and installation of the new microsoft/git version. ```APIDOC Windows Installation: Install `microsoft/git` from the official release. Description: The installer for `microsoft/git` on Windows automatically removes the .NET version of Scalar and updates registered enlistments. Command: (Installer executable, e.g., `microsoft-git-installer.exe`) macOS Installation: Uninstall existing Scalar and install `microsoft/git` via Homebrew. Description: Removes previous Scalar versions and installs the new version, requiring re-registration of enlistments. Commands: brew uninstall --cask scalar brew uninstall --cask scalar-azrepos brew install --cask microsoft-git scalar register Parameters: --cask: Specifies that the package is a cask (GUI application or command-line tool). Returns: Status messages from Homebrew and Scalar commands. Linux Installation: Remove the .NET version and install the new `scalar` binary. Description: Manually removes the old Scalar installation and overwrites the binary with the new version. Enlistments require re-registration. Commands: sudo rm -rf /usr/local/lib/scalar/ (Install new version, typically by placing the binary in /usr/local/bin) scalar register Parameters: -rf: Recursive and force removal of directories and their contents. Returns: Status messages from shell commands. ``` -------------------------------- ### Build Scalar on Windows Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Execute this batch script to build the Scalar project on a Windows environment. Ensure Visual Studio and .NET Core SDK are installed as per the prerequisites. ```batch Scripts\BuildScalarForWindows.bat ``` -------------------------------- ### Method Naming Convention Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Method names should start with a verb to clearly indicate the action performed by the method, improving readability and consistency. ```C# // Preferred: public string GetProjectedFolderEntryData() { ... } // Avoid: public string ProjectedFolderEntryData() { ... } ``` -------------------------------- ### Self-Commenting Code Example Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Write self-commenting code where possible. When comments are necessary, they should provide background context or explain non-obvious logic, rather than stating the obvious. ```C# // Order the folders in descending order so that we walk the tree from bottom up. // Traversing the folders in this order: // 1. Ensures child folders are deleted before their parents // 2. Ensures that folders that have been deleted by git // (but are still in the projection) are found before their // parent folder is re-expanded (only applies on platforms // where EnumerationExpandsDirectories is true) foreach (PlaceholderListDatabase.PlaceholderData folderPlaceholder in placeholderFoldersListCopy.OrderByDescending(x => x.Path)) { // ... process folderPlaceholder ... } ``` -------------------------------- ### Avoid Broad Exception Catching for Programmer Errors in C# (Bad Practice) Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Shows an anti-pattern where broad exception handling (`catch(Exception)`) is used, potentially masking programmer errors and making debugging difficult. This example also demonstrates nested try-catch blocks which can obscure the origin of errors. ```csharp bool TryDoWorkOnDisk(string fileContents, out string error) { try { CreateReadConfig(); CreateTempFile(fileContents); RenameTempFile(); } catch (Exception ex) when (ex is IOException || ex is UnauthorizedAccessException) { error = "Something went wrong doing work on disk"; try { if (TempFileExists()) { DeleteTempFile(); } } catch (Exception e) when (e is IOException || e is UnauthorizedAccessException) { error += ", and failed to cleanup temp file"; } return false; } error = null; return true; } ``` -------------------------------- ### Build Scalar for Windows Source: https://github.com/microsoft/scalar/blob/main/AuthoringTests.md Instructions for building the Scalar project on Windows, either via Visual Studio or a batch script. This step is crucial before running functional tests. ```batch Scripts\BuildScalarForWindows.bat ``` -------------------------------- ### Build Scalar for Mac Source: https://github.com/microsoft/scalar/blob/main/AuthoringTests.md Instructions for building the Scalar project on macOS using a shell script. This is a prerequisite for running functional tests on Mac. ```bash Scripts/Mac/BuildScalarForMac.sh ``` -------------------------------- ### Scalar Update and Verification Commands Source: https://github.com/microsoft/scalar/blob/main/Readme.md Instructions for verifying the new Scalar version and registering enlistments for future upgrades across different operating systems. ```APIDOC Scalar Version Check: scalar version Description: Checks the installed Scalar version. The output should match the core Git version. Returns: The version string of the Scalar executable. Scalar Registration: scalar register Description: Registers Git enlistments for future upgrades. This command is necessary on macOS and Linux after installing the new version. Parameters: (No explicit parameters, operates on the current enlistment) Returns: Status indicating successful registration or errors. Related Commands: git version: Verifies the underlying Git installation version. ``` -------------------------------- ### dtruss Command Usage and Options Source: https://github.com/microsoft/scalar/blob/main/Scripts/Mac/Tracing/Tracing.md Documentation for the dtruss command-line utility, detailing its usage, new options for filtering and process tracing, and improvements over the stock version. Covers non-root execution, improved syscall logging, and handling of child processes. ```APIDOC dtruss [-options] Description: Launches a command using dtruss for system call tracing. Improvements over stock dtruss: - Non-root execution: Commands can be run as a non-privileged admin user, with dtrace running as root via sudo. - Correct logging of execve() and posix_spawn() syscalls. - Improved output for syscalls with buffer or string parameters (handling NULL pointers, large buffers). - Enhanced reliability for following child processes, including those created with posix_spawn(). Options: -F Filters out common but typically uninteresting syscalls. Currently filters out close() calls returning EBADF. -f Follows child processes. This mode is more reliable, supporting processes created with posix_spawn(). -b Specifies the dynamic variable memory size. Useful for increasing buffer capacity when many traced events occur (e.g., -b 100m). Remaining bugs/limitations: - dtruss no longer exits when the specified command exits (regression from non-privileged launch change). - Some syscalls may still be badly formatted in trace output. - Buffers can fill up and miss events under heavy tracing load, indicated by 'dtrace: dynamic variable drops...'. Increase memory with -b or narrow tracing focus. - Currently, only all syscalls or a single syscall can be traced, not a specific subset. ``` -------------------------------- ### Run Functional Tests on Windows Source: https://github.com/microsoft/scalar/blob/main/AuthoringTests.md Command to execute functional tests on Windows. Requires running the command prompt as Administrator and specifying the build configuration (Debug/Release). ```batch Scripts\RunFunctionalTests.bat Debug --test=Scalar.FunctionalTests.Tests.EnlistmentPerFixture.CloneTests.CloneToPathWithSpaces ``` -------------------------------- ### Log Exceptions with Contextual Metadata in C# Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Demonstrates how to log exceptions with additional contextual metadata for easier root-cause analysis. This approach enhances debugging by including relevant details like package version and name alongside the exception stack trace. ```csharp catch (Exception e) { EventMetadata metadata = new EventMetadata(); metadata.Add("Area", "Upgrade"); metadata.Add(nameof(packageVersion), packageVersion); metadata.Add(nameof(packageName), packageName); metadata.Add("Exception", e.ToString()); context.Tracer.RelatedError(metadata, $"Failed to compare {packageName} version"); } ``` -------------------------------- ### Clone Scalar Repository Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md This command clones the Scalar project repository from GitHub. It is the first step for setting up your local development environment. ```git git clone https://github.com/microsoft/scalar scalar/src ``` -------------------------------- ### Prefer TryXXX Pattern for Error Handling in C# (Good Practice) Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Illustrates the recommended 'TryXXX' pattern for handling operations that might fail, avoiding exceptions for normal control flow. This method returns a boolean indicating success and uses an 'out' parameter for error messages, making error handling explicit and efficient. ```csharp bool TryDoWorkOnDisk(string fileContents, out string error) { if (!TryCreateReadConfig()) { error = "Failed to read config file"; return false; } if (!TryCreateTempFile(fileContents)) { error = "Failed to create temp file"; return false; } if (!TryRenameTempFile()) { error = "Failed to rename temp file"; if (!TryDeleteTempFile()) { error += ", and failed to cleanup temp file"; } return false; } error = null; return true; } ``` -------------------------------- ### Run Functional Tests on Mac Source: https://github.com/microsoft/scalar/blob/main/AuthoringTests.md Command to execute functional tests on macOS. Requires specifying the build configuration (Debug/Release) and can include specific test filters. ```bash Scripts/Mac/RunFunctionalTests.sh Debug --test=Scalar.FunctionalTests.Tests.EnlistmentPerFixture.CloneTests.CloneToPathWithSpaces ``` -------------------------------- ### Customizing Functional Test Settings Source: https://github.com/microsoft/scalar/blob/main/AuthoringTests.md The functional test settings, including paths and URLs, can be customized in the Settings.cs file within the Scalar.FunctionalTests project. ```csharp Scalar.FunctionalTests\Settings.cs ``` -------------------------------- ### Save dtruss Output to File and Terminal Source: https://github.com/microsoft/scalar/blob/main/Scripts/Mac/Tracing/Tracing.md Demonstrates how to save dtruss output to a file while also displaying it on the terminal using the tee command. This is useful for real-time monitoring and persistent logging. ```shell sudo dtruss -p 1000 2> >(tee clang-trace.txt >&2) ``` -------------------------------- ### Running Specific Functional Tests Source: https://github.com/microsoft/scalar/blob/main/AuthoringTests.md Functional tests can be filtered by providing a comma-separated list of test names using the --test argument. The test name must include the full namespace and class. ```csharp --test=Scalar.FunctionalTests.Tests.EnlistmentPerFixture.CloneTests.CloneToPathWithSpaces ``` -------------------------------- ### Capture Syscall Trace with dtruss Source: https://github.com/microsoft/scalar/blob/main/Scripts/Mac/Tracing/Tracing.md Captures a trace of system calls made by a specific command, saving output to a file and displaying it simultaneously. This is a quick way to diagnose failing commands. ```shell ++path-to-vfs4g-source++/Scripts/Mac/Tracing/dtruss -d -e -F -f ++command-to-run++ 2> >(tee ++trace-filename.txt++ >&2) ``` -------------------------------- ### Background Thread Exception Handling Pattern Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Wrap all code running on background threads or long-running tasks in a top-level `try/catch(Exception)`. Log any caught exceptions and then force the process to terminate using `Environment.Exit` to ensure stability after an unhandled exception. ```C# try { // Code that runs in the background thread or long-running task } catch (Exception ex) { // Log the exception details Console.Error.WriteLine($"Unhandled exception in background task: {ex}"); // Force termination of the process Environment.Exit(1); } ``` -------------------------------- ### Scalar Features Overview Source: https://github.com/microsoft/scalar/blob/main/Readme.md Scalar enhances Git performance for large repositories by enabling advanced features. These features reduce clone times, improve working directory size, and accelerate command execution. ```text Scalar enables advanced Git features such as: * Partial clone * Background prefetch * Sparse-checkout * File system monitor * Commit-graph * Multi-pack-index * Incremental repack ``` -------------------------------- ### Trace Processes by PID with dtruss Source: https://github.com/microsoft/scalar/blob/main/Scripts/Mac/Tracing/Tracing.md Traces system calls for a specific process identified by its Process ID (PID) using the -p flag. This is useful when you know the exact process to monitor. ```shell sudo dtruss -p 1000 ``` -------------------------------- ### Trace Named Processes with dtruss Source: https://github.com/microsoft/scalar/blob/main/Scripts/Mac/Tracing/Tracing.md Traces system calls for processes matching a given name using the -n flag. Note that process names in macOS are limited to 16 characters (MAXCOMLEN). ```shell sudo ./Scripts/Mac/Tracing/dtruss -d -e -n clang ``` -------------------------------- ### Trace Child Processes Recursively with dtruss Source: https://github.com/microsoft/scalar/blob/main/Scripts/Mac/Tracing/Tracing.md Traces the activity of a command and all processes launched by it recursively using the -f flag. This is ideal for diagnosing complex build processes or multi-process applications. ```shell ./Scripts/Mac/Tracing/dtruss -d -e -f xcodebuild ``` -------------------------------- ### C# Unit Test Exception Handling Tag Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Illustrates the use of the `ExceptionExpected` category attribute in C# unit tests. This tag is applied when either the test code or the product code is expected to throw an exception, preventing the test from running when a debugger is attached. ```csharp [TestCase] [Category(CategoryConstants.ExceptionExpected)] public void ParseFromLsTreeLine_NullRepoRoot() ``` -------------------------------- ### Null Check Convention Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Use the equality (`==`) and inequality (`!=`) operators for checking `null` values, rather than the `is` operator. ```C# // Preferred: if (myObject != null) { ... } // Avoid: if (myObject is object) { ... } // If myObject is null, this evaluates to false ``` -------------------------------- ### Use `nameof` for Identifiers Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Utilize the `nameof` operator instead of hardcoded strings for identifiers like variable or method names. This ensures that references are updated automatically if the identifier is renamed. ```C# string methodName = nameof(MyMethod); Console.WriteLine($"Executing method: {methodName}"); // Preferred for logging/reflection: // nameof(MyMethod) will update if MyMethod is renamed. // Avoid for identifiers: // string methodName = "MyMethod"; // This string will not update if MyMethod is renamed. ``` -------------------------------- ### Prefer Explicit Types and Avoid `var` Source: https://github.com/microsoft/scalar/blob/main/CONTRIBUTING.md Prefer concrete types over interfaces (e.g., `List` over `IList`) and avoid implicitly typed local variables (`var`). This makes performance and thread-safety characteristics explicit. ```C# // Preferred: List names = new List(); // Avoid: var names = new List(); ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.