From c8a619b7f2bd6a67b010cf991f64921244abe265 Mon Sep 17 00:00:00 2001 From: Jon McGuire Date: Sun, 26 Aug 2018 14:45:55 -0400 Subject: [PATCH 1/3] first real instructions --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/README.md b/README.md index 672358f..662cba6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,64 @@ # dotnet-curses This is an easy-to-use, fully cross-platform .NET Standard 2.0 wrapper for the Unix NCurses terminal library. The project is able to load the OS-specific native implementation of NCurses at runtime which means you can deploy the same binary to Windows, Linux, or OSX. Most other .NET wrappers use statically-defined references to the native implementation, requiring different builds for different OSes. +## Status / TODO +The library itself is tested and fully functional. Remaining tasks: + +- Set up Travis CI to validate pull requests +- Set up AppVeyor builds and NuGet packaging +- Additional sample programs +- Wrap more of the ncurses API + ## Usage +NuGet packaging is on the way, but for now, I recommend forking this project to your own repo, clonining it locally, then changing the csproj to generate a local NuGet package that you can reference from your own application. This way any dependencies will be automatically resolved by NuGet. + +As explained in the introductory paragraph, this library assumes your application will be compiled as a portable executable. That results in a DLL that can run on Windows, Linux, or OSX, and this library works the same way. At runtime it detects the OS and loads the native OS-specific version of the curses library. Later sections explain how to get the correct .NET runtime on Linux or OSX, how to find an ncurses implementation for Windows, and what to do if ncurses on your OS uses a non-standard library name (generally only a problem on Linux). + +In your own program, you're mainly calling static methods exposed by the `NCurses` class in the `Mindmagma.Curses` namespace. I recommend browsing the `NCurses` class in the Visual Studio object browser window to see exactly what is available (at the time of writing, 91 API calls are available). + +How to use the curses API itself is beyond the scope of this README. I recommend reading either [this](http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html) high-level introduction or the much longer article by Eric S. Raymond [here](https://invisible-island.net/ncurses/ncurses-intro.html). However, a typical start-up sequence might look like this: + +```csharp +var Screen = NCurses.InitScreen(); +NCurses.NoDelay(Screen, true); +NCurses.NoEcho(); +``` + +## The .NET Runtime +The target OS doesn't need to install the developer-oriented .NET SDK. Instead, a much smaller, machine-wide .NET runtime can be installed. + +For Windows, there is a simple installer [here](https://www.microsoft.com/net/download?initial-os=windows). + +The same is true of OSX, download an installer [here](https://www.microsoft.com/net/download?initial-os=macos). + +As usual, Linux makes it complicated. Your best bet is to read the documentation about preprequisites [here](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x) and follow the instructions that match your distro. Because distros can vary considerably even between minor releases, you should try to match your _exact_ distro and version for the best chances of success. + +## The Native Library +OSX always installs ncurses. Linux distros _almost_ always do (if yours does not, unfortunately I probably can't help you). + +For Windows, download it from Thomas Dickey’s site (the current ncurses maintainer) from the 64-bit link under tje "MinGW Ports" heading, and extract the DLLs anywhere in your `%PATH%`: + +https://invisible-island.net/ncurses/#download_mingw + +## Non-Standard Library Filenames +Various platforms, releases and distributions have used different filenames for the curses library. On OSX it usually includes the major version number, and on Linux it's common to include the major and minor version numbers. Windows has never included a cursors implementation, although Thomas Dickey's builds are the de facto standard. + +The _dotnet-curses_ library contains a list of defaults for each platform that are very likely to work. However, if you want to add to these or even replace one or more lists entirely, simply add a class to your project that derives from `CursesLibraryNames` and override one or more of the following: + +- `bool ReplaceWindowsDefaults` +- `bool ReplaceLinuxDefaults` +- `bool ReplaceOSXDefaults` +- `List NamesWindows` +- `List NamesLinux` +- `List NamesOSX` + +The "Replace" properties are false by default. That means if you override the corresponding name list, those names will be added to the _dotnet-curses_ default list. If you set a "Replace" property to true, the built-in defaults will be ignored, and only the names you provide will be used. + +Currently the default lists are: + +- Windows: `libncursesw6.dll` +- Linux: `libncurses.so.5.9`, `libncurses.so` +- OSX: `libncurses.dylib` + +## Native Library Loader +This project includes a separate slightly-modified copy of Eric Mellinoe's [NativeLibraryLoader](https://github.com/mellinoe/nativelibraryloader/) project. The project is serving as a prototype for implementing improved native library support directly in a future version of .NET Core (probably 2.2). From 75db02844eb14a62ae3481678d9dbd66807f798c Mon Sep 17 00:00:00 2001 From: Jon McGuire Date: Sun, 26 Aug 2018 14:48:46 -0400 Subject: [PATCH 2/3] fixed typos --- README.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 662cba6..4e51f44 100644 --- a/README.md +++ b/README.md @@ -25,20 +25,14 @@ NCurses.NoEcho(); ``` ## The .NET Runtime -The target OS doesn't need to install the developer-oriented .NET SDK. Instead, a much smaller, machine-wide .NET runtime can be installed. - -For Windows, there is a simple installer [here](https://www.microsoft.com/net/download?initial-os=windows). - -The same is true of OSX, download an installer [here](https://www.microsoft.com/net/download?initial-os=macos). +The target OS doesn't need to install the developer-oriented .NET SDK. Instead, a much smaller, machine-wide .NET runtime can be installed. For Windows, there is a simple installer [here](https://www.microsoft.com/net/download?initial-os=windows). The same is true of OSX, download an installer [here](https://www.microsoft.com/net/download?initial-os=macos). As usual, Linux makes it complicated. Your best bet is to read the documentation about preprequisites [here](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x) and follow the instructions that match your distro. Because distros can vary considerably even between minor releases, you should try to match your _exact_ distro and version for the best chances of success. ## The Native Library OSX always installs ncurses. Linux distros _almost_ always do (if yours does not, unfortunately I probably can't help you). -For Windows, download it from Thomas Dickey’s site (the current ncurses maintainer) from the 64-bit link under tje "MinGW Ports" heading, and extract the DLLs anywhere in your `%PATH%`: - -https://invisible-island.net/ncurses/#download_mingw +For Windows, download it from Thomas Dickey’s site (the current ncurses maintainer) from the 64-bit link under the "MinGW Ports" heading on [this page](https://invisible-island.net/ncurses/#download_mingw), and extract the DLLs anywhere in your `%PATH%`. ## Non-Standard Library Filenames Various platforms, releases and distributions have used different filenames for the curses library. On OSX it usually includes the major version number, and on Linux it's common to include the major and minor version numbers. Windows has never included a cursors implementation, although Thomas Dickey's builds are the de facto standard. @@ -61,4 +55,4 @@ Currently the default lists are: - OSX: `libncurses.dylib` ## Native Library Loader -This project includes a separate slightly-modified copy of Eric Mellinoe's [NativeLibraryLoader](https://github.com/mellinoe/nativelibraryloader/) project. The project is serving as a prototype for implementing improved native library support directly in a future version of .NET Core (probably 2.2). +This project includes a separate slightly-modified copy of Eric Mellinoe's [_NativeLibraryLoader_](https://github.com/mellinoe/nativelibraryloader/) project. The project is serving as a prototype for implementing improved native library support directly in a future version of .NET Core (probably 2.2). From 9b932d5a939617b568d94269c89e4f0f4a1979da Mon Sep 17 00:00:00 2001 From: Jon McGuire Date: Sun, 26 Aug 2018 14:54:14 -0400 Subject: [PATCH 3/3] improved override info --- README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 4e51f44..9fc32eb 100644 --- a/README.md +++ b/README.md @@ -37,18 +37,20 @@ For Windows, download it from Thomas Dickey’s site (the current ncurses mainta ## Non-Standard Library Filenames Various platforms, releases and distributions have used different filenames for the curses library. On OSX it usually includes the major version number, and on Linux it's common to include the major and minor version numbers. Windows has never included a cursors implementation, although Thomas Dickey's builds are the de facto standard. -The _dotnet-curses_ library contains a list of defaults for each platform that are very likely to work. However, if you want to add to these or even replace one or more lists entirely, simply add a class to your project that derives from `CursesLibraryNames` and override one or more of the following: +The _dotnet-curses_ library contains a list of defaults for each platform that are very likely to work. However, if you want to add to these or even replace one or more lists entirely, simply add a class to your project that derives from `CursesLibraryNames` and use one or more of the following: -- `bool ReplaceWindowsDefaults` -- `bool ReplaceLinuxDefaults` -- `bool ReplaceOSXDefaults` -- `List NamesWindows` -- `List NamesLinux` -- `List NamesOSX` +```csharp +public override bool ReplaceWindowsDefaults => true; +public override bool ReplaceLinuxDefaults => true; +public override bool ReplaceOSXDefaults => true; +public override List NamesWindows => new List { "abc.dll", "xyz.dll" }; +public override List NamesLinux => new List { "abc.1.5.so", "abc.so" }; +public override List NamesOSX => new List { "xyz5.dylib", "xyz.dylib" }; +``` -The "Replace" properties are false by default. That means if you override the corresponding name list, those names will be added to the _dotnet-curses_ default list. If you set a "Replace" property to true, the built-in defaults will be ignored, and only the names you provide will be used. +The "Replace" properties are false by default. If you leave it at the default but override the corresponding name list, those names will be **added** to the _dotnet-curses_ default list. However, if you override and set a "Replace" property to true, the built-in defaults will be ignored, and only the names you provide will be used. -Currently the default lists are: +Currently the names built into _dotnet-curses_ are as follows and should work for most target environments: - Windows: `libncursesw6.dll` - Linux: `libncurses.so.5.9`, `libncurses.so`