Generate shell.nix for development in the local workspace

Closes #24.

README.md

@@ -35,11 +35,24 @@ you don't have to be concerned with it.
    ```sh
    ros2nix $(find -name package.xml)
    ```
-   This also creates `./overlay.nix` and `./default.nix` for easy
-   integration and/or testing of created packages.
+   This also creates `./shell.nix` for development in the local
+   workspace and `./overlay.nix` and `./default.nix` for easy
+   integration and/or testing of created Nix packages.
+
+2. To build the local workspace with `colcon`, run:
+
+   ```sh
+   nix-shell
+   colcon build
+   ```
+
+   If `nix-shell` fails, it might be due to missing packages in
+   `nixpkgs` or `nix-ros-overlay`. Feel free to submit a bug or
+   provide the package in `extraPkgs` argument.
+
+3. To build some of your packages with Nix, replace `my-package` with
+   a real name and run:
 
-2. Try building some of your packages (replace `my-package` with real
-   name):
    ```sh
    nix-build -A rosPackages.humble.my-package
    nix-build -A rosPackages.jazzy.my-package
@@ -106,6 +119,79 @@ the [Autoware][] project as an example.
 
 [Autoware]: https://autoware.org/
 
+## Working with development environments
+
+By default, `ros2nix` generates `shell.nix` file, which declares
+development environment for compilation of your workspace. In the
+simplest case, you can enter it by running `nix-shell`. For greater
+flexibility, you can extend it as described below.
+
+### ROS distribution
+
+By default, `nix-shell` enters the ROS distribution which was
+specified by `--distro` option of `ros2nix`, which defaults to
+`rolling`. If you want to change it, rerun `ros2nix` with different
+value of `--distro=...`.
+
+Alternatively, you can override the default distribution when invoking
+`nix-shell`:
+
+    nix-shell --argstr rosDistro jazzy
+
+### Adding other packages
+
+The generated `shell.nix` has three parameters `withPackages`,
+`extraPkgs` and `extraPaths`, which you can use to extend or modify
+the development environment.
+
+Use `withPackages` to add additional packages to the environment.
+Define a Nix function, which returns the packages from the given
+package set (`p` in the example below):
+
+    nix-shell --arg withPackages 'p: with p; [ compressed-image-transport ]'
+
+This command ensures that `compressed-image-transport` plugin will be
+available in your development environment in addition to other
+required packages. You can use more (space separated) packages inside
+`[ ]`. Put there any [ROS package](https://index.ros.org/) (just
+replace `_` with `-`) or any package from
+[nixpkgs](https://search.nixos.org/packages).
+
+Parameters `extraPkgs` and `extraPaths` are meant for programmatic use
+and are described in the next section.
+
+### Making the changes permanent
+
+
+
+### Running graphical applications
+
+Since Nix environments aim to be completely independent from your host
+system (unless it's NixOS), Nix-compiled programs don't use user space
+portions of graphics drivers from your host distribution. Therefore,
+running most graphical applications like `rviz2` fails. There are
+multiple possible solutions, but we recommend using
+[nix-system-graphics][].
+
+If you have Intel or AMD GPU, follow their [install
+instructions][nix-system-graphics-install]. In a nutshell:
+
+1. Store `flake.nix` from their README into an empty directory.
+2. Run there `nix run 'github:numtide/system-manager' -- switch --flake .`.
+
+This will create a few files in `/etc/systemd/system` that will create
+`/run/opengl-driver` (location where Nix programs expect graphics
+drivers).
+
+If you have NVIDIA GPU, the setup is more complex because you need to
+manually select the same version of the driver as the one used by the
+kernel of your host system.
+
+[nix-system-graphics]: https://github.com/soupglasses/nix-system-graphics
+[nix-system-graphics-install]: https://github.com/soupglasses/nix-system-graphics?tab=readme-ov-file#installing-with-nix-flakes
+
+### Automatically entering the environment
+
 ## ros2nix reference
 
 <!-- `$  python3 -m ros2nix --help` -->
@@ -121,8 +207,9 @@ usage: ros2nix [-h]
                [--extra-check-inputs DEP1,DEP2,...]
                [--extra-native-build-inputs DEP1,DEP2,...] [--flake]
                [--default | --no-default] [--overlay | --no-overlay]
-               [--nix-ros-overlay FLAKEREF] [--nixfmt] [--compare]
-               [--copyright-holder COPYRIGHT_HOLDER] [--license LICENSE]
+               [--shell | --no-shell] [--nix-ros-overlay FLAKEREF] [--nixfmt]
+               [--compare] [--copyright-holder COPYRIGHT_HOLDER]
+               [--license LICENSE]
                package.xml [package.xml ...]
 
 positional arguments:
@@ -195,6 +282,7 @@ options:
                         None)
   --overlay, --no-overlay
                         Generate overlay.nix (default: True)
+  --shell, --no-shell   Generate shell.nix (default: True)
   --nix-ros-overlay FLAKEREF
                         Flake reference of nix-ros-overlay. You may want to
                         change the branch from master to develop or use your