Aptivi - Manual
ProjectsWebsiteBlog
Nitrocid KS - Manual
Nitrocid KS - Manual
  • Welcome!
  • Versions and Compatibility
    • Supported Versions
    • EOL Versions
    • Version Release Notes
      • v0.0.1.x series
      • v0.0.2.x series
      • v0.0.3.x series
      • v0.0.4.x series
      • v0.0.5.x series
        • v0.0.5.0 Beta Versions
      • v0.0.6.x series
        • v0.0.6.0 Beta Versions
      • v0.0.7.x series
        • v0.0.7.0 Beta Versions
      • v0.0.8.x series
      • v0.0.9.x series
      • v0.0.10.x series
      • v0.0.11.x series
      • v0.0.12.x series
      • v0.0.13.x series
      • v0.0.14.x series
      • v0.0.15.x series
      • v0.0.16.x series
      • v0.0.17.x series
      • v0.0.18.x series
      • v0.0.19.x series
      • v0.0.20.x series
      • v0.0.21.x series
      • v0.0.22.x series
      • v0.0.23.x series
      • v0.0.24.x series
      • v0.1.0.x and 0.1.1.x series
      • v0.1.2.x and v0.1.3.x series
    • Compatibility Notes for KS API Revisions
      • Upgrading to API v1.0 series
      • Upgrading to API v1.1 series
      • Upgrading to API v1.2 series
      • Upgrading to API v1.3 series
      • Upgrading to API v2.0 series
      • Upgrading to API v2.1 series
      • Upgrading to API v3.0 series
        • From 0.0.24.x to 0.1.0 Beta 1
        • From 0.1.0 Beta 1 to 0.1.0 Beta 2
        • From 0.1.0 Beta 2 to 0.1.0 Beta 3
        • From 0.1.0 Beta 3 to 0.1.0 RC
        • From 0.1.0 RC to 0.1.0 Final
      • Upgrading to API v3.1 series
  • Installation and Maintenance
    • Installing the Kernel
      • Windows
      • macOS
      • Linux
      • Android
    • Upgrading the Kernel
      • Windows
      • macOS
      • Linux
      • Android
    • Dependency Information
  • Fundamentals
    • What is the Kernel?
    • What is Nitrocid KS?
    • Simulated Kernel Features
      • Extra Features
        • More Networking
          • FTP Client
          • SSH Connection
          • SFTP Client
          • RSS Client
          • HTTP Client
          • Mail Client
        • Games and Amusements
          • Hangman
          • BackRace
          • Meteor
          • Pong
          • Russian Roulette
          • ShipDuet
          • Snaker
          • Solver
          • SpeedPress
          • Wordle
        • More Editors
          • JSON Editor
          • SQL Editor
        • Common Programs
          • Archive
          • Caffeine
          • Calendar
          • Calculator
          • Contacts
          • Dictionary
          • Git Shell
          • Notes
          • Stocks
          • Timers
          • To-do List
          • Unit Converter
          • Weather
        • Docking
        • Language Studio
        • Theme Studio
      • Accounts
        • Groups
        • Permissions
      • Editors
        • Text Editor
        • Hex Editor
      • Shells
        • Commands List
        • Addon Commands List
      • Files and Folders
        • Hashing and Encryption
      • The Nitrocid Homepage
      • Networking
      • Localization
      • Screensavers
      • Lockscreen Widgets
      • Audio Cues
  • Advanced and Power Users
    • Building the Kernel
      • Building on Windows
      • Building on macOS
      • Building on Linux
      • Building on Android
    • Kernel Modifications
      • Building your Mod
      • Analyzing your Mod
        • Text - NKS0001
        • ConsoleBase - NKS0002
        • ConsoleBase - NKS0003
        • ConsoleBase - NKS0004
        • ConsoleBase - NKS0005
        • ConsoleBase - NKS0006
        • ConsoleBase - NKS0007
        • ConsoleBase - NKS0008
        • ConsoleBase - NKS0009
        • Files - NKS0010
        • Files - NKS0011
        • Files - NKS0012
        • Files - NKS0013
        • Files - NKS0014
        • Files - NKS0015
        • Files - NKS0016
        • Files - NKS0017
        • Files - NKS0018
        • Files - NKS0019
        • Files - NKS0020
        • Files - NKS0021
        • Files - NKS0022
        • Files - NKS0023
        • Kernel - NKS0024
        • Kernel - NKS0025
        • Kernel - NKS0026
        • Kernel - NKS0027
        • Kernel - NKS0031
        • Kernel - NKS0032
        • Kernel - NKS0033
        • Kernel - NKS0037
        • Kernel - NKS0038
        • Kernel - NKS0039
        • Kernel - NKS0040
        • Kernel - NKS0041
        • Kernel - NKS0042
        • Kernel - NKS0043
        • Kernel - NKS0052
        • Kernel - NKS0053
        • Languages - NKS0044
        • Languages - NKS0045
        • Languages - NKS0046
        • Network - NKS0051
        • Text - NKS0047
        • Text - NKS0048
        • Text - NKS0049
        • Text - NKS0050
        • Text - NKS0054
        • Text - NKS0055
      • Managing your Mod
        • Inter-Mod Communication
        • Inter-Addon Communication
    • Diagnostics
      • Debugging
        • Local Debugging
        • Remote Debugging
      • Testing
      • Other Diagnostics
    • Bootloader
      • Boot Choices
      • Kernel Environments
      • Custom Boot Styles
    • Inner Workings
      • Kernel Settings
        • Mechanics of Settings App
        • Settings Format
        • Custom Settings
      • Shell Structure
        • Help System
        • Command Parsing
        • Command Information
        • Command Switches
        • Shell History
        • Shell Scripting
        • Shell Presets
        • Extra Shell Features
      • Multilingual Kernel
        • Locale Tools
        • Custom Languages
      • Inner Essentials
        • Kernel Drivers
          • Console Drivers
          • Debug Logger Drivers
          • Encoding Drivers
          • Encryption Drivers
          • Filesystem Drivers
          • Hardware Prober Drivers
          • Input Drivers
          • Network Drivers
          • RNG Drivers
          • Regular Expression Drivers
          • Sorting Drivers
        • Kernel Placeholders
        • The Permissions
        • The Users
        • Kernel Threads
        • Kernel Arguments
        • Kernel Journaling
        • Remote Procedure
        • Nitrocid Filesystem
        • Screensaver Internals
        • Splash Internals
        • Kernel Platform
        • Theme Internals
        • Color Internals
        • Privacy Consents
        • System Notifications
        • MAL and MOTD
        • Progress Handlers
        • Assembly Signing
        • Assembly Reflection
        • Random Number Generation
        • Network Tools
        • Date and Time
        • Mod Manual Pages
      • Miscellaneous APIs
  • Project Dependencies
  • Report an issue
  • Source code
  • API Reference
Powered by GitBook
On this page
  • From 0.1.1 to 0.1.2
  • Updated Terminaux to 6.1
  • Detailed important changes
Edit on GitHub
  1. Versions and Compatibility
  2. Compatibility Notes for KS API Revisions

Upgrading to API v3.1 series

Follow the compatibility notes when upgrading your mods to API v3.1 series

Last updated 2 months ago

As API v3.1 is still in development, the breaking changes get committed and land here. They describe what broke and what should be used instead.

From 0.1.1 to 0.1.2

This version gives your kernel a nice ink of paint that brings in feature additions and spectacular improvements in all fields, including some of the cosmetic changes.

Updated Terminaux to 6.1

We've updated Terminaux to 6.1 to bring improvements. However, this doesn't come without the cost of having to deal with the breaking changes, which, in this case, is many.

You can consult the list of breaking changes that result from upgrading to Terminaux 6.1 by pressing the below button:

Detailed important changes

This section explains how to adapt the important changes to your mod code so that it works with 0.1.2 and higher. This highlights the most important changes that we have compiled for you.

Removed modern debug log look

KernelMainConfig.cs
public bool DebugLegacyLogStyle { get; set; } = true;

We have removed the modern debug log look introduced in the 0.1.0 series, because although it provided a more comfortable look for log reading, we've considered it as a flawed goal due to problems that may come with it, such as log timing differences.

It's advisable for you to stop using this feature.

Removed SplashDisplaysProgress

BaseSplash.cs
public virtual bool SplashDisplaysProgress => Info.DisplaysProgress;
ISplash.cs
bool SplashDisplaysProgress { get; }

The above property has been removed, because the SplashInfo instance already contains information about whether the splash displays progress information or not. This removal is necessary to maintain consistency.

It's advisable for you to stop using this property.

Removed ConfigCategory

ConfigCategory.cs
public enum ConfigCategory

This enumeration went unused as the 0.1.0 configuration has been remade with speed and serialization in mind. Therefore, it got removed as it's of no use. Also, it's limited to only specifying the categories in the main kernel configuration, none of which apply to other configurations, including the custom configuration instances that your mods may install.

A viable alternative, GetSettingsEntries(), can be used to get the categories from all configurations.

Merged ListLanguages() and ListLanguagesWithCountry() functions

LanguageManager.cs
public static Dictionary<string, LanguageInfo> ListAllLanguagesWithCountry()
public static Dictionary<string, LanguageInfo> ListLanguagesWithCountry(string SearchTerm)

The above functions have been merged with the ListLanguages() function and it got an extra boolean parameter that does exactly the same thing. The reason was that because we wanted to avoid code repetition.

If you still want to list languages with their countries in the key, you can now move to ListLanguages, passing true to the last optional argument.

Aptivestigate is used for debugger and crash handler

KernelMainConfig.cs
public bool DebugQuotaCheck { get; set; }
public int DebugQuotaLines { get; set; } = 10000;

As a consequence, you'll have to implement the DebugLevel argument in your debug logger implementation like this:

public override void Write(string text, DebugLevel level)
{ }

public override void Write(string text, DebugLevel level, params object[] vars)
{ }

In addition to that, Aptivestigate uses the following paths to log the events:

  • Windows: %LOCALAPPDATA%/Aptivi/Logs

  • Unix: ~/.config/Aptivi/Logs

This caused us to remove the Debugging kernel path to ensure that all logs that are logged by applications using Aptivestigate are logged in one place.

KernelPathType.cs
public enum KernelPathType
{
    (...)
    Debugging,
    (...)
}
PathsManagement.cs
public static string DebuggingPath

Aptivestigate will continue to get updated, despite the low frequency of updates, which is expected. It will be expanded to allow you to control the logging behavior.

Screensaver properties are get-only

IScreensaver.cs
string ScreensaverName { get; set; }
bool ScreensaverContainsFlashingImages { get; set; }
BaseScreensaver.cs
public virtual string ScreensaverName { get; set; } = "BaseScreensaver";
public virtual bool ScreensaverContainsFlashingImages { get; set; } = false;

The two overridable properties mentioned above have been inappropriately declared to be settable, despite them being read-only informational properties. In order to maintain consistency, we've decided to remove the setter from the property so that you can override them only once. This ensures that all the information present in the screensaver instances are correct.

You should edit the overridden properties so that they don't expose the setters.

Culture management is separate from the language management

KernelMainConfig.cs
// Removed
public bool LangChangeCulture { get; set; }

// Renamed to CurrentCultureName
public string CurrentCultStr { get; set; } = "en-US";
CultureManager.cs
// Removed
public static void UpdateCultureDry()
public static void UpdateCulture()
public static CultureInfo[] GetCulturesFromCurrentLang()
public static List<string> GetCultureNamesFromCurrentLang()
public static CultureInfo[]? GetCulturesFromLang(string Language)
public static List<string>? GetCultureNamesFromLang(string Language)

// Renamed to CurrentCulture
public static CultureInfo CurrentCult =>
    new(Config.MainConfig.CurrentCultStr);
LanguageInfo.cs
// Removed
public string CultureCode =>
    cultureCode;
public CultureInfo[] Cultures =>
    cultures;
    
// Modified to remove cultureCode
public LanguageInfo(string LangName, string FullLanguageName, bool Transliterable, int Codepage = 65001, string cultureCode = "", string country = "")
public LanguageInfo(string LangName, string FullLanguageName, bool Transliterable, string[]? LanguageToken, string cultureCode = "", string country = "")
LanguageManager.cs
// Removed
public static string InferLanguageFromSystem()

To allow users more flexibility into choosing their own culture that is recognized by the kernel, the above functions that are tagged as removed above are deleted from the public API.

There are no alternatives for this.

Removed WelcomeMessage from the public API

WelcomeMessage.cs
public static class WelcomeMessage

This class was not meant to be used by the kernel mods in the first place, because it contained code that was utilized by the kernel startup sequence, which would be inappropriate to use once the kernel boots up. We've decided to remove this class from the API to prevent misuse.

There are no alternatives for this.

Removed fancy console writers

public static class TextFancyWriters
public static class TextMiscWriters

The above classes have been removed, because Terminaux 7.0 is planned to remove the old-school function-based writers, which were marked as obsolete thanks to the new cyclic writers. Those writers were in use by the above static classes.

SelectionFunctionType changes

When using the above settings entry key, you'll need to provide the fully-qualified type name, not just a short name. This is to avoid ambiguity.

Merged filesystem operation classes

All operation classes
public static class (OperationName)

// Relocated to FilesystemTools partial class
public static partial class FilesystemTools

To avoid fragmentation in the filesystem tools, such as Opening, Listing, and Checking, we've decided to merge such classes, except those that are not directly related to the filesystem operation, to the FilesystemTools partial class in the Nitrocid.Files namespace.

You'll need to update your using clause to point to Nitrocid.Files and to update your references to such classes to point to FilesystemTools.

CheckConfigVariables() simplified for SMultivar support

ConfigTools.cs
public static Dictionary<string, bool> CheckConfigVariables()
public static Dictionary<string, bool> CheckConfigVariables(string configTypeName)
public static Dictionary<string, bool> CheckConfigVariables(BaseKernelConfig? entries)
public static Dictionary<string, bool> CheckConfigVariables(SettingsEntry[]? entries, BaseKernelConfig? config)

The above function's return value has changed to List<bool>. Consequently, you'll no longer be able to get information about which variable is for which, because we've omitted the configuration names.

In the final version of 0.1.2, we promise to restore the original functionality, but it's going to use a tuple instead of a dictionary because of a potential of multiple settings keys, especially the SMultivar keys, that can hold the same name in the same configuration entry.

Inter-addon and inter-mod communication updated

We've updated the inter-addon and the inter-mod communication so that you can work with the mods and the addons with more depth. See the changes here.

Added info-based reflection functions

FieldManager.cs
// UseGeneral removed
public static object? GetFieldValue(string Variable, Type? VariableType, bool UseGeneral = false)

// Entire function removed
public static FieldInfo? GetFieldGeneral(string Variable)
PropertyManager.cs
// UseGeneral removed
public static object? GetPropertyValue(string Variable, Type? VariableType, bool UseGeneral = false)

// Entire function removed
public static PropertyInfo? GetPropertyGeneral(string Variable)

We've added reflection functions that used the following:

  • MethodBase: for method reflection

  • FieldInfo: for field reflection

  • PropertyInfo: for property reflection

As a consequence, we've removed the Get*General() functions due to internal structural changes in regards to the configuration reading mechanism, as well as have changed the signature of the Get*Value() functions so that they don't have an optional parameter, UseGeneral, anymore.

Get*Value() functions are already aware of the settings-related properties.

Moved Nitrocid.Modifications to the Nitrocid.Extras.Mods addon

This affects all the classes except the most essential ones and the inter-mod communication class. They have been moved to this addon, so even the kernel requires the usage of the inter-addon communication in order to be able to utilize mod functions.

This is done to prevent the Lite version of Nitrocid KS from being able to run any mod, provided that the necessary mod code, including the starting functions, have been moved to that addon.

You can use the inter-addon communication to be able to interact with this addon, since these classes remain public.

Nitrocid.LocaleGen.Core removed

This NuGet package didn't expose any public API since its inception. It was originally meant to be as a plan for 0.1.0.x to consolidate all the LocaleGen projects and their siblings into one, but it seems that it was never done as of the release of the second beta of 0.1.0.

Now, we've completed the work of consolidation, removing Nitrocid.LocaleGen.Core in the process, resulting in such NuGet package being deprecated without an alternative. Additionally, all the internal projects and LocaleGen itself have been migrated into one application that is to be included in the main Nitrocid build output, Nitrocid.Locales.

Debug writer changed for CompilerServices attributes

DebugWriter.cs
public static void WriteDebugPrivacy(DebugLevel Level, string text, int[] SecureVarIndexes, params object?[]? vars)
public static void WriteDebug(DebugLevel Level, string text, params object?[]? vars)
public static void WriteDebugLogOnly(DebugLevel Level, string text, params object?[]? vars)
public static void WriteDebugConditional(bool Condition, DebugLevel Level, string text, params object?[]? vars)
public static void WriteDebugDevicesOnly(DebugLevel Level, string text, bool force, params object?[]? vars)
public static bool WriteDebugDeviceOnly(DebugLevel Level, string text, bool force, RemoteDebugDevice device, params object?[]? vars)
public static void WriteDebugChatsOnly(DebugLevel Level, string text, bool force, params object?[]? vars)

The debug writer's functions have been edited to include three new arguments before the vars parameter. However, the following types were used:

  • memberName: string [CallerMemberName attribute]

  • memberLine: int [CallerLineNumber attribute]

  • memberPath: string [CallerFilePath attribute]

Additionally, the nature of params in the last argument, along with the usage of an array of any object (as indicated by object?[]?), causes these functions to allow you to supply infinite arguments without having to explicitly create an array.

Because of potential conflicts, we've decided to convert the vars argument to a normal parameter with the default value of null. This is going to break the build, as you'll have to change how you call the functions.

public static void Assert(bool condition, ...)
public static void AssertNot(bool condition, ...)
public static void AssertNull<T>(T value, ...)
public static void AssertNotNull<T>(T value, ...)
public static void AssertFail(string message, ...)

This also affects all the above Assert() functions found in the DebugCheck class.

You'll have to change how you call these functions. Don't worry; you'll just have to append the vars: prefix and create an array just like any other array that holds your variables for text formatting. For example:

DebugWriter.WriteDebug(DebugLevel.I, "Hi, {0}!", vars: ["Nitrocid KS"]);

Refactored console tools

ConsoleTools.cs
public static class ConsoleTools
{
    (...)
    public static void ResetColors(bool useKernelColors = false)
    public static void ResetBackground(bool useKernelColors = false)
    public static void ResetForeground(bool useKernelColors = false)
    (...)
}

The above functions have been moved to the KernelColorTools class. Since those functions were the only functions that were made to the public, with no properties or fields set to public, we've decided to mark the ConsoleTools class as internal.

You can still use these functions in the KernelColorTools class.

Automatic update downloads removed

KernelMainConfig.cs
public bool AutoDownloadUpdate { get; set; } = true;

Since we're working on improvements for Nitrocid KS to ensure that it gets updated seamlessly and only when required, we've decided to stop the automatic update downloads by removing the feature. This ensures that we can provide distraction-free user experience.

It's advisable to stop using this configuration entry.

Removed the NTFS mitigation for the 2021 corruption

FilesystemTools.cs
public static void ThrowOnInvalidPath(string? Path)

However, NuGet back then assumed that the version published contained "malware" that actually checked the path string with Contains(). This was the e-mail:

Package KS 0.0.15 owned by your account was identified as malware and deleted.

— NuGet team, "Malware detected in a NuGet.org package"

Our intention was not to inject "malware" into the final distribution, so we'd negotiated with the NuGet team about the clarification of our checking method, and this was their response:

Both the 0.0.15 version and the 0.0.14.2 versions of your KS package triggered our malware detection/validation. The 0.0.15 version was deleted for this reason (our malware analysis team concluded it was malicious). However, given extra details you provided and this is the second instance of the problem, I have submitted the details you provided to our malware analysis team for further review.

Apologies on the delay but, to be safe, we cannot allow this package to complete validation until there is a conclusive response from our malware analysis team. Our team takes the security of our customers extremely seriously and depend on our partner teams to evaluate packages for malware.

In general, if Windows 10 is identifying a package or package contents as malware as a “false positive”, package consumers will run into the very same problem that you and our malware validation is encountering. Therefore, I believe it is best to work with the malware analysis team to resolve this issue conclusively.

— NuGet team

Fast forward to the present, this check was no longer necessary, because almost all computers were patched, so we've decided to remove the check, this time, at will instead of being forced.

However, some scanners may still detect your mod as "malware," so we don't recommend re-implementing this function at all.

Theme preview function simplified

ThemePreviewTools.cs
public static void PreviewThemeSimple(string theme)
public static void PreviewThemeSimple(ThemeInfo theme)

As we've implemented the color viewer in Terminaux, we've finally removed the "simple" version of the theme preview and merged its functionality with the normal version.

This is a behavioral change.

Base shell info generic class implemented

BaseShellInfo.cs
public abstract class BaseShellInfo : IShellInfo

When you create your own shell info classes to give your shell some important information, such as commands and other info, you had to override the BaseShell property so that it returned a new instance of your shell. However, this can be a hassle in certain scenarios.

Starting from Nitrocid KS 0.1.2 and Terminaux 7.0, you'll no longer have to override the BaseShell property because we've implemented a generic version of the above class that takes a type of your shell. For example, if your shell is called OxygenShell and your shell info class is called OxygenShellInfo, you can just inherit the generic version of the class so that it becomes BaseShellInfo<OxygenShell>.

As a result, the following properties are removed from the IShellInfo interface:

IShellInfo.cs
BaseShell? ShellBase { get; }
PromptPresetBase CurrentPreset { get; }

When inheriting the non-generic base shell class, your shell info class might hold wrong information about your shell, even if your commands are defined. Therefore, you must migrate to the generic version of the class if you want to retain your shell settings.

Removed unused function from SwitchInfo

SwitchInfo.cs
public string GetTranslatedHelpEntry() =>
    Translate.DoTranslation(HelpDefinition);

This function was just a small wrapper to get the translated version of the help entry. The localization tools are now able to detect unlocalized strings more efficiently than before, and we felt that this function was just a syntax sugar, so we've decided to remove this function as mods can now have translatable strings.

You can use Translate.DoTranslation() against the HelpDefinition property to achieve the same goal.

Moved WriteWrapped to TextDynamicWriters

TextWriters.cs
public static void WriteWrapped(string Text, bool Line, KernelColorType colorType, params object[] vars)
public static void WriteWrapped(string Text, bool Line, KernelColorType colorTypeForeground, KernelColorType colorTypeBackground, params object[] vars)

TextDynamicWriters wasn't affected in the direct upgrade from 0.1.0 or 0.1.1 to 0.1.2, because Terminaux 6.0 had deprecated the WriteListEntry() functions and that 6.1 had undone the deprecation due to its importance.

Additionally, WriteWrapped has been moved to TextDynamicWriters and WriteListEntry() has been re-introduced.

Removed changelogs kernel update type

UpdateKind.cs
public enum UpdateKind
{
    (...)
    Changelogs,
}

We've removed the Changelogs type from the update type enumeration, because we've changed how we bundle the changelogs with the application. Earlier, we used to grab the changelogs from the GitHub release section of Nitrocid KS. Now, we've made the changelogs fully offline by using embedded resources instead.

UpdateManager.cs
public static KernelUpdate? FetchChangelogs()
public static string GetVersionChangelogs()

As a result, we've removed the above functions from UpdateManager.

We will no longer ship the changes.chg file with the GitHub release section starting from the next 0.1.2 release. You'll have to use versioned tags to get the file from tools/changes.chg instead.

As is now used to handle unhandled crashes and to facilitate the work of the debugger with the help of , which already provides the quota system, we've decided to remove the two above settings entries to improve log rotation.

Consult the Terminaux documentation for more information on how to use the cyclic writers .

When we were working on the 0.0.15.0 version of Nitrocid KS (Kernel Simulator back then), we became aware of the NTFS bug causing Windows 10 systems that didn't have the fix to display the "disk corrupt" message when "accessing" the NTFS bitmap, leading the users into rebooting the PC to check the whole disk. We also became aware of the kernel driver bug that caused a crash of the system with Blue Screen of Death (BSOD) when the system tried to access an arbitrary path. As a response, we've released that version with the fix applied as per commit .

Meanwhile, we'd released the clean version under the 0.0.14.3 version with commit . The NuGet team then allowed us to push newer versions of Nitrocid KS with the checking code included.

You can still implement this code, referring to that caused this breaking change, in your mod. However, because this part of code is licensed with GNU GPL 3.0+, you'll have to credit the whole project by preserving the license header found at the top of the code file of Nitrocid KS.

Aptivestigate
Serilog
here
aa8250c
a8d45c3
this commit
API v6.0Breaking changes for API v6.0