From b3710421df72ec1c7fdc257668150f11bb350843 Mon Sep 17 00:00:00 2001 From: Minijackson Date: Thu, 21 Sep 2023 13:49:21 +0200 Subject: [PATCH] doc/ioc/getting-started: use semantic breaks --- doc/ioc/tutorials/getting-started.md | 212 +++++++++++++++++++-------- 1 file changed, 150 insertions(+), 62 deletions(-) diff --git a/doc/ioc/tutorials/getting-started.md b/doc/ioc/tutorials/getting-started.md index 138bf8e3..ef39b934 100644 --- a/doc/ioc/tutorials/getting-started.md +++ b/doc/ioc/tutorials/getting-started.md @@ -6,50 +6,72 @@ title: Getting started The requirements for using EPNix are having curl, Nix, and Git installed. -If you need to install Nix, you also need the `xz` utility, often part of the `xzip` or `xz` package. +If you need to install Nix, +you also need the `xz` utility, +often part of the `xzip` or `xz` package. -You *don't* need to have EPICS base installed globally, EPNix makes it available to you when you enter your top's development shell. +You *don't* need to have EPICS base installed globally, +EPNix makes it available to you +when you enter your top's development shell. # Installing Nix ::: callout-warning -If you use a Linux distribution with SELinux, be sure to turn it off. +If you use a Linux distribution with SELinux, +be sure to turn it off. You can do this by adding the line `SELINUX=disabled` in `/etc/sysconfig/selinux` on distributions based on RedHat Enterprise Linux (RHEL) like CentOS, Rocky Linux, and so on. ::: -If you don't have Nix installed, first follow the [official instructions]. +If you don't have Nix installed, +first follow the [official instructions]. -Unless you use WSL2, use the multi-user installation, because it builds packages in an isolated environment. +Unless you use WSL2, +use the multi-user installation, +because it builds packages in an isolated environment. [official instructions]: https://nixos.org/download.html#download-nix # Enabling Nix flakes and the `nix`{.bash} command -Because Nix flakes and the unified `nix` command are experimental features at the time of writing, you need to enable them in your `/etc/nix/nix.conf`. +Because Nix flakes and the unified `nix` command are experimental features at the time of writing, +you need to enable them in your `/etc/nix/nix.conf`. -To enable this feature, add this line to your `/etc/nix/nix.conf`: +To enable this feature, +add this line to your `/etc/nix/nix.conf`: ``` ini experimental-features = nix-command flakes ``` -If you have installed Nix in multi-user mode, then you have to restart the Nix daemon with `systemctl restart nix-daemon.service`{.bash}. +If you have installed Nix in multi-user mode, +then you have to restart the Nix daemon with `systemctl restart nix-daemon.service`{.bash}. # Untracked files and Nix flakes -One important thing with Nix flakes: when your flake is in a Git repository, Nix only considers files that Git tracks. +One important thing with Nix flakes: +when your flake is in a Git repository, +Nix only considers files that Git tracks. -For example, if your `flake.nix`, is in a repository, and you create a file `foobar.txt`, you must run `git add [-N] foobar.txt`{.bash} to make Nix recognize it. +For example, +if your `flake.nix` is in a Git repository, +and you create a file `foobar.txt`, +you must run `git add [-N] foobar.txt`{.bash} to make Nix recognize it. This prevents copying build products into the Nix store. # Concepts -In EPNix, your IOC have mainly one important file: the `flake.nix` file. +In EPNix, +your IOC have mainly one important file: +the `flake.nix` file. -The `flake.nix` file is the entry point that the `nix`{.bash} command reads in order for `nix build`{.bash}, `nix flake check`{.bash}, and `nix develop`{.bash} to work. -It's also the file where you specify your other "repository" dependencies. -For example, your IOC depends on EPNix itself, and also depends on each external EPICS "app." +The `flake.nix` file is the entry point that the `nix`{.bash} command reads +in order for `nix build`{.bash}, `nix flake check`{.bash}, and `nix develop`{.bash} to work. +It's also the file +where you specify your other "repository" dependencies. +For example, +your IOC depends on EPNix itself, +and also depends on each external EPICS "app." The `flake.nix` file also contains the configuration of your EPNix top. EPNix provides a list of possible options and you can [extend them yourself]. @@ -61,14 +83,21 @@ The [Available options] page of the documentation book documents the options pro # Creating your project ::: callout-note -Verify that you have set up your computer so that you can clone your repositories unattended, with for example SSH keys or tokens. -If you intend to use private Git repositories, see the [Private repository setup] guide. +Verify that you have set up your computer +so that you can clone your repositories unattended, +with for example SSH keys or tokens. +If you intend to use private Git repositories, +see the [Private repository setup] guide. ::: -With EPNix, we recommend developers to version EPICS tops separate from EPICS apps. -This means that by default, Git ignores apps created with `makeBaseApp.pl`, so that you can create separate Git repositories for them. +With EPNix, +we recommend developers to version EPICS tops separate from EPICS apps. +This means that by default, +Git ignores apps created with `makeBaseApp.pl`, +so that you can create separate Git repositories for them. -If you use an old system and see Git errors while creating your template, you can install a recent version of Git by running `nix-env -iA nixpkgs.git` after installing Nix. +If you use an old system and see Git errors while creating your template, +you can install a recent version of Git by running `nix-env -iA nixpkgs.git` after installing Nix. To kick-start an EPNix project: @@ -107,11 +136,13 @@ git add . ... ``` -Now that your EPICS app is in a remote repository, you can instruct EPNix to use your created app from the remote repository: +Now that your EPICS app is in a remote repository, +you can instruct EPNix to use your created app from the remote repository: Edit your top's `flake.nix` -- Below the other inputs, add: +- Below the other inputs, + add: ``` nix inputs.exampleApp = { @@ -124,12 +155,18 @@ And, under the EPNix options section: - add `"inputs.exampleApp"`{.nix} in the `applications.apps` list (the quotes are necessary) -Now, Nix tracks your app from the remote repository, and tracks its Git version in the `flake.lock` file. +Now, Nix tracks your app from the remote repository, +and tracks its Git version in the `flake.lock` file. -You can test that your top builds by executing: `nix build -L`{.bash}. This puts a `./result` symbolic link in your top's directory containing the result of the compilation. +You can test that your top builds by executing: +`nix build -L`{.bash}. +This puts a `./result` symbolic link in your top's directory containing the result of the compilation. ::: callout-tip -As a rule, each time you edit the `flake.nix` file, or update your inputs by running `nix flake update`{.bash} or `nix flake lock`{.bash}, you should leave and re-enter your development shell (`nix develop`{.bash}). +As a rule, +each time you edit the `flake.nix` file, +or update your inputs by running `nix flake update`{.bash} or `nix flake lock`{.bash}, +you should leave and re-enter your development shell (`nix develop`{.bash}). ::: [Private repository setup]: ../guides/private-repo-setup.md @@ -140,93 +177,141 @@ As a rule, each time you edit the `flake.nix` file, or update your inputs by run ## Using Nix -As said earlier, running `nix build`{.bash} compiles your IOC. -This builds your top and all your dependencies, from a clean environment, by using your apps from remote Git repositories. +As said earlier, +running `nix build`{.bash} compiles your IOC. +This builds your top and all your dependencies, +from a clean environment, +by using your apps from remote Git repositories. Nix places the output under `./result`. -When developing your IOC, it can become cumbersome that Nix tracks the remote repository of your app. -You sometimes want to do some temporary changes to your app, and test them before committing. - -For this exact purpose, EPNix includes a handy command called `enix-local`{.bash}. -This command behaves the same as `nix`, but instead uses your apps as-is from your local directory. - -For example, if you have started your EPNix project as in the [earlier section], you should have your top and a directory `exampleApp` under it. -Therefore, if you run `nix develop`{.bash}, then `enix-local build -L`{.bash} in the development shell, Nix will build your top, with the modifications from your local `exampleApp` directory. - -The advantage of using Nix when developing is that it builds from a "cleaner" environment. -It also stores the result in the Nix store, which you can copy by using the `nix copy`{.bash} command, and test it on another machine. +When developing your IOC, +it can become cumbersome +that Nix tracks the remote repository of your app. +You sometimes want to do some temporary changes to your app, +and test them before committing. + +For this exact purpose, +EPNix includes a handy command called `enix-local`{.bash}. +This command behaves the same as `nix`, +but instead uses your apps as-is from your local directory. + +For example, +if you have started your EPNix project as in the [earlier section], +you should have your top and a directory `exampleApp` under it. +Therefore, +if you run `nix develop`{.bash}, +then `enix-local build -L`{.bash} in the development shell, +Nix will build your top, +with the modifications from your local `exampleApp` directory. + +The advantage of using Nix when developing is +that it builds from a "cleaner" environment. +It also stores the result in the Nix store, +which you can copy by using the `nix copy`{.bash} command, +and test it on another machine. [earlier section]: #creating-your-project ## Using standard tools The EPNix development shell (`nix develop`{.bash}) includes your standard build tools. -This means that after creating your project, you can use `make`{.bash} as in any other standard EPICS development. +This means that after creating your project, +you can use `make`{.bash} as in any other standard EPICS development. -The difference is that Git doesn't track `configure/RELEASE.local` and `configure/CONFIG_SITE.local` files, because they contain variables necessary to build with the EPNix environment. +The difference is that Git doesn't track `configure/RELEASE.local` and `configure/CONFIG_SITE.local` files, +because they contain variables necessary to build with the EPNix environment. They contain for example the `EPICS_BASE` variable. To add them to your top, you can run `eregen-config`{.bash}. ::: callout-tip -As a rule, each time you edit your modules in `flake.nix`, you should leave and re-enter your development shell, and re-run `eregen-config`{.bash}. +As a rule, +each time you edit your modules in `flake.nix`, +you should leave and re-enter your development shell, +and re-run `eregen-config`{.bash}. ::: -The advantage of using the standard tools, is that the compilation is incremental. -Nix always builds a package fully, meaning it always compiles your top from scratch. -Using `make`{.bash} directly only re-compiles the modified files, at the cost of potential impurities in your build. +The advantage of using the standard tools, +is that the compilation is incremental. +Nix always builds a package fully, +meaning it always compiles your top from scratch. +Using `make`{.bash} directly only re-compiles the modified files, +at the cost of potential impurities in your build. # Upgrading your app version -After you have modified, tested, committed, and pushed your app changes, you should update your top so that your app version points to the latest version. +After you have modified, tested, committed, and pushed your app changes, +you should update your top +so that your app version points to the latest version. -To do this, you can run: +To do this, +you can run: ``` bash nix flake lock --update-input exampleApp --commit-lock-file ``` -This command updates the `exampleApp` input, and creates a Git commit for this update. +This command updates the `exampleApp` input, +and creates a Git commit for this update. -This command also works if you want to update the `epnix` input, or the `nixpkgs` input containing the various needed packages used by EPICS. +This command also works if you want to update the `epnix` input, +or the `nixpkgs` input containing the various needed packages used by EPICS. # Looking up the documentation -EPNix includes documentation: it has a documentation book (what you are reading), and man pages. +EPNix includes documentation: +it has a documentation book (what you are reading) and man pages. -To see the documentation book, run `edoc`{.bash} in the development shell from your top directory. +To see the documentation book, +run `edoc`{.bash} in the development shell from your top directory. -To see the man page, run `man epnix-ioc`{.bash} in the development shell from your top directory. +To see the man page, +run `man epnix-ioc`{.bash} in the development shell from your top directory. # Adding dependencies -You now have all the tools you need to have a self-contained EPICS IOC, but it's quite useful to depend on modules from the community. +You now have all the tools you need to have a self-contained EPICS IOC, +but it's quite useful to depend on modules from the community. EPNix provides a way to do it. -The first step is to examine the documentation, either the `epnix-ioc(5)` man page, under the "AVAILABLE PACKAGES" section, or in the documentation book, under the "Available packages" page. +The first step is to examine the documentation, +either the `epnix-ioc(5)` man page, +under the "AVAILABLE PACKAGES" section, +or in the documentation book under the "Available packages" page. -If the package exists, you can add this bit to your `flake.nix` file. +If the package exists, +you can add this bit to your `flake.nix` file. ``` nix support.modules = with pkgs.epnix.support; [ your_dependency ]; ``` -If the package doesn't exist, you can try [packaging it yourself], or you can request it in the [EPNix issue tracker]. +If the package doesn't exist, +you can try [packaging it yourself], +or you can request it in the [EPNix issue tracker]. [packaging it yourself]: ../developer-guides/packaging.md [EPNix issue tracker]: https://github.com/epics-extensions/EPNix/issues # Deploying your IOC -To deploy your IOC, build it by using Nix. -If you are doing a production deployment, verify that you have a clean build, by not using `enix-local`, and having a clean top Git repository. +To deploy your IOC, +build it by using Nix. +If you are doing a production deployment, +verify that you have a clean build, +by not using `enix-local`, +and having a clean top Git repository. -With this, you get a `./result` symbolic link to the result in the Nix store, which you can copy, with all its dependencies, using `nix copy`. -The only prerequisite is that the remote machine has Nix installed too. +With this, +you get a `./result` symbolic link to the result in the Nix store, +which you can copy, with all its dependencies, using `nix copy`. +The only prerequisite is +that the remote machine has Nix installed too. -For example, if you want to copy a built IOC to the machine `example-ioc.prod.mycompany.com`: +For example, +if you want to copy a built IOC to the machine `example-ioc.prod.mycompany.com`: ``` bash nix copy ./result --to ssh://root@example-ioc.prod.mycompany.com @@ -234,7 +319,8 @@ nix copy ./result --to ssh://root@example-ioc.prod.mycompany.com This copies the build in the Nix store and every dependencies to the remote machine. -To run the program, you can get where the build is by inspecting the symbolic link on your local machine: +To run the program, +you can get where the build is by inspecting the symbolic link on your local machine: ``` bash readlink ./result @@ -250,7 +336,8 @@ Now you can run the IOC on the remote machine. -If you want to do automated, declarative, or more complex deployments, we highly recommend using NixOS and optionally one of its deployment tools ([NixOps], [morph], [disnix], [colmena]) . +If you want to do automated, declarative, or more complex deployments, +we highly recommend using NixOS and optionally one of its deployment tools ([NixOps], [morph], [disnix], [colmena]) . You can also use non-NixOS hosts. @@ -262,7 +349,8 @@ You can also use non-NixOS hosts. # Pitfalls -Although tries to resemble standard EPICS development, some differences might lead to confusion. +Although EPNix tries to resemble standard EPICS development, +some differences might lead to confusion. You can find more information about this in the [FAQ].