From e543be68564a54cfaf7180a9f2e724905d06a749 Mon Sep 17 00:00:00 2001 From: Aaron Bockover Date: Thu, 13 Jun 2019 17:21:56 -0400 Subject: README.md big update for VS for Mac --- README.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a51db21..6884212 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,92 @@ # Microsoft Visual Studio Editor API -This repository contains Microsoft Visual Studio Editor public API representing text model, text logic and text view subsystems of the editor. -For more information about Visual Studio Editor architecture see [Inside the Editor](https://msdn.microsoft.com/en-us/library/dd885240.aspx). -This API is typically used to build Visual Studio extensions. +This repository contains the open source layers of the Microsoft Visual +Studio editor. This includes all public API definitions and some low level +implementations of the editor including the text model, text logic, and +editor primitives & operations subsystems. These layers are intended for +extension authors to better integrate with the editor. -# Installation +With a few caveats, the layers in this repository power both Visual +Studio on Windows and the Visual Studio for Mac editors. While both editors +are built on this codebase, many aspects of the editor are not open source, +including the WPF and Cocoa UI layers. -Visual Studio Editor API is shipping as the following Nuget packages and also gets installed with Visual Studio Extension Development workload. +## Visual Studio for Mac + +Visual Studio for Mac 8.1 [introduced a brand new native macOS text editor](https://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2019-mac-relnotes#---new-c-editor) +built on the "real" Visual Studio editor core. Central to our ongoing effort +to bring parity and performance benefits to developers by leveraging and +sharing more code with Visual Studio on Windows, the UI layers were ported +directly from WPF to modern Cocoa. + +Most notably, the Cocoa editor uses Apple's +[Core Text](https://developer.apple.com/documentation/coretext), +[Core Graphics](https://developer.apple.com/documentation/coregraphics), and +[Core Animation](https://developer.apple.com/documentation/quartzcore) +technologies to perform retained-mode layout and high fidelity rendering of +text. Among other enhancements for and integrations with macOS, it +now supports all of the macOS input methods via the +[`NSTextInputClient`](https://developer.apple.com/documentation/appkit/nstextinputclient) +protocol. + +Currently, the new native editor based on Visual Studio and the legacy editor +co-exist while we transition all language services away from the legacy +editor. Visual Studio for Mac supports C# and XAML (in 8.2 previews) so far, +but will continue to enable support for other languages over the coming +releases. Please refer to the +[Visual Studio for Mac roadmap](https://docs.microsoft.com/en-us/visualstudio/productinfo/mac-roadmap) +for details on what's next. + +This diagram should help visualize the layering of Visual Studio for Mac +compared to Visual Studio while the legacy editor still exists for some +languages. + +![Visual Studio for Mac Editor Architecture](https://docs.microsoft.com/en-us/visualstudio/mac/media/vs-editor-architecture.png) + +## Caveats + +In order to facilitate porting the WPF editor from Windows to macOS, some +breaking changes have been made to some of the lower-level interfaces. The +ongoing plan is to reconcile these differences such that there is no API +difference whatsoever between the WPF and Cocoa editors. + +For now, however, there are two separate sets of NuGet packages for targeting +Visual Studio and Visual Studio for Mac, available in the respective sections +below. + +While _most_ non-UI related interfaces are identical across WPF and Cocoa +implementations of the editor, many are new yet familiar: when targeting +Cocoa, `ICocoa*` interfaces can generally be found in place of analogous +`IWpf*` interfaces. + +## Resources + +The following resources should help extension authors become familiar with +the editor APIs and capabilities, and are relevant to both Visual Studio +and Visual Studio for Mac. + +* [Managed Extensibility Framework](https://docs.microsoft.com/dotnet/framework/mef/index) +* [MEF in the Editor](https://docs.microsoft.com/visualstudio/extensibility/managed-extensibility-framework-in-the-editor) +* [Inside the Editor](https://docs.microsoft.com/visualstudio/extensibility/inside-the-editor) +* [Language Service and Editor Extension Points](https://docs.microsoft.com/visualstudio/extensibility/language-service-and-editor-extension-points) +* [A video introduction to the editor architecture](https://www.youtube.com/watch?v=PkYVztKjO9A) + +## Editor SDK Installation + +### Visual Studio for Mac + +NuGet packages are forthcoming, but all assemblies are available to extensions +for Visual Studio for Mac when using Add-in Maker. The assemblies can also be +produced directly from this repository (see +[Building the Editor API](#build-the-editor-api) below). + +Refer to the [Extending Visual Studio for Mac](https://docs.microsoft.com/en-us/visualstudio/mac/extending-visual-studio-mac) documentation for details. + + +### Visual Studio (Windows) + +On Windows, the Visual Studio Editor API is available via NuGet and is also +installed with the Visual Studio Extension Development workload. Note that | Nuget package | Current version | | ------------- | ------------- | @@ -14,3 +94,45 @@ Visual Studio Editor API is shipping as the following Nuget packages and also ge | [Microsoft.VisualStudio.Text.Data](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Data) | [![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Text.Data.svg)](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Data) | | [Microsoft.VisualStudio.Text.Logic](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Logic) | [![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Text.Logic.svg)](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Logic) | | [Microsoft.VisualStudio.Text.UI](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.UI) | [![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Text.UI.svg)](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.UI) | + +## Building The Editor API + +While this repository is largely intended for reference, it can produce a +viable build of the lower levels of the editor. Either open `VSEditorCore.sln` +in Visual Studio or Visual Studio for Mac and build from the IDE, or build +on the command line. + +Visual Studio 2019 or Visual Studio for Mac 8.0 or newer is required. + +### Build + +Assemblies will be available in the `bin/` directory at the root of the +repository. + +```bash +$ msbuild /restore +``` + +### Package + +NuGet packages may also be produced locally and will be available in +the `_artifacts/nuget/` directory at the root of the repository. + +```bash +$ msbuild /t:Pack +``` + +## Contributing + +This project has adopted the +[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the +[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) +or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any +additional questions or comments. + +### Pull Requests + +We are generally not accepting pull requests for this repository for the +core editor code at this time. Please feel free to submit pull requests for +other content in this repository, including new samples. \ No newline at end of file -- cgit v1.2.3