docs: document IOC module deprecation

docs/ioc/user-guides/deprecations/index.rst

@@ -0,0 +1,10 @@
+Deprecations
+============
+
+Guides for how to migrate your code
+due to a deprecation in the EPNix project
+
+.. toctree::
+   :titlesonly:
+
+   ./migrating-from-modules-development.rst

docs/ioc/user-guides/deprecations/migrating-from-modules-development.rst

@@ -0,0 +1,172 @@
+Migrating from modules development
+==================================
+
+.. deprecated:: 25.05
+
+   Developing IOC using NixOS-like modules
+
+Explanation
+-----------
+
+NixOS-like modules were used to define your IOC,
+for example using code such as this:
+
+.. code-block:: nix
+   :caption: Deprecated IOC definition
+
+   myEpnixConfig = {pkgs, ...}: {
+     epnix = {
+       inherit inputs;
+
+       meta.name = "my-top";
+
+       support.modules = with pkgs.epnix.support; [StreamDevice];
+
+       checks.imports = [./checks/simple.nix];
+
+       nixos.services.ioc = {
+         app = "example";
+         ioc = "iocExample";
+       };
+     };
+   };
+
+This style of development is deprecated since EPNix version ``nixos-25.05``
+and will be removed in EPNix version ``nixos-26.05``.
+
+This style of development was deprecated
+because it lead to complex logic inside of EPNix,
+and provided no tangible benefit.
+Moreover,
+support top IOCs are packaged differently inside of EPNix,
+in a style much more similar to what you can find in nixpkgs.
+
+The newer way of developing IOCs is more similar to the Nix code you can find in the wild,
+which makes public documentation more applicable to EPNix developments.
+
+Copying the new template
+------------------------
+
+From the top directory of your IOC,
+move your :file:`flake.nix` file and checks out of the way,
+and initialize the new template over your project:
+
+.. code-block:: bash
+   :caption: Applying the new template
+
+   mv flake.nix flake.nix.old
+   mv checks checks.old
+   nix flake init -t epnix
+
+Edit the new template
+---------------------
+
+Flake
+^^^^^
+
+For every flake input that you added in your :file:`flake.nix.old` file,
+add them in your new :file:`flake.nix` file.
+
+For every overlay that's in your :file:`flake.nix.old`'s ``nixpkgs.overlays`` attribute,
+add them in your new :file:`flake.nix` file,
+in ``pkgs``' ``overlays``.
+
+Change the name of your IOC by replacing every instance of ``myIoc`` in :file:`flake.nix`.
+
+IOC package
+^^^^^^^^^^^
+
+Edit the :file:`ioc.nix` file to match your IOC:
+
+- Change the ``name``, ``version``, and ``varname`` variables
+- Add your EPICS support modules dependencies into ``propagatedBuildInputs``
+- Add your system libraries dependencies into both ``nativeBuildInputs`` and ``buildInputs``
+
+If you had :samp:`buildConfig.attrs.{something} = {value};` defined in :file:`flake.nix.old`,
+add :samp:`{something} = {value};` to your :file:`ioc.nix` file.
+
+Checks
+^^^^^^
+
+For each :file:`checks.old/{check}.nix` file directory,
+take the new :file:`checks/simple.nix` as a base and:
+
+- copy the ``testScript`` from your old check into the new one
+- if you made changes to ``nodes`` or ``nodes.machine``,
+  add them to the new check
+
+External apps (IEE)
+-------------------
+
+If you defined external apps in :file:`flake.nix.old` such as this:
+
+.. code-block:: nix
+   :caption: Deprecated usage of external apps
+
+   application.apps = [
+     "inputs.exampleApp"
+   ];
+
+You will need to copy them manually in :file:`ioc.nix`.
+
+
+To do this,
+make sure you've re-added :samp:`inputs.{example}App` to your new :file:`flake.nix`,
+and pass your ``inputs`` as argument to your IOC:
+
+.. code-block:: diff
+   :caption: :file:`flake.nix`
+
+    overlays.default = final: _prev: {
+   -  myIoc = final.callPackage ./ioc.nix {};
+   +  myIoc = final.callPackage ./ioc.nix { inherit inputs; };
+    };
+
+.. code-block:: diff
+   :caption: :file:`ioc.nix`
+
+    {
+      mkEpicsPackage,
+      lib,
+      epnix,
+   +  inputs,
+    }:
+    mkEpicsPackage {
+      pname = "myIoc";
+
+Copy your apps manually,
+during the ``preConfigure`` phase.
+For example,
+if you have two apps ``exampleApp`` and ``otherExampleApp``:
+
+.. code-block:: nix
+   :caption: :file:`ioc.nix`
+   :emphasize-lines: 6-11
+
+   #local_release = {
+   #  PCRE_INCLUDE = "${lib.getDev pcre}/include";
+   #  PCRE_LIB = "${lib.getLib pcre}/lib";
+   #};
+
+   preConfigure = ''
+     echo "Copying exampleApp"
+     cp -rTvf --no-preserve=mode ${inputs.exampleApp} ./exampleApp
+     echo "Copying otherExampleApp"
+     cp -rTvf --no-preserve=mode ${inputs.otherExampleApp} ./otherExampleApp
+   '';
+
+   meta = {
+     description = "A description of my IOC";
+     homepage = "<homepage URL>";
+     # ...
+   };
+
+NixOS machines
+--------------
+
+If you have in a single project both a NixOS configuration and an IOC,
+you need to adapt your code to package your IOC outside of NixOS modules.
+
+The simplest way to do that
+is by separating your IOC into a new project,
+and follow the migration guide from there.

docs/ioc/user-guides/index.rst

@@ -16,5 +16,6 @@ User guides
    ./reccaster.rst
    ./mrf-devices.rst
    ./testing/index.rst
+   ./deprecations/index.rst
 
 .. TODO: make a NixOS test user-guide

docs/release-notes/2505.rst

@@ -0,0 +1,14 @@
+25.05 Release notes
+===================
+
+.. default-domain:: nix
+
+.. role:: nix(code)
+   :language: nix
+
+Breaking changes
+----------------
+
+- The old way of developing IOCs was deprecated,
+  and will be removed in version ``nixos-26.05``.
+  Please follow the migration guide :doc:`../ioc/user-guides/deprecations/migrating-from-modules-development`.