expanded

source/new-flake/python-flake/main.adoc0

@@ -22,6 +22,20 @@ $ curl https://codeberg.org/mhwombat/hello-flake-python/raw/branch/main/hello.py
 $# cat hello.py
 ....
 
+== Running the program manually (optional)
+
+[NOTE]
+====
+In this section you will learn how to do some development tasks manually, the "hard" way.
+This can help you understand the distinction between Nix's role and
+the Python build system you've chosen.
+Also, if you have a build problem but you're not sure if the fault is in
+your flake definition or some other configuration file,
+these commands can help you narrow it down.
+But you may wish to skip to the <<_configuring_setuptools,next section>>
+and come back here later.
+====
+
 Before we package the program, let's verify that it runs. We're going to
 need Python. By now you've probably figured out that we can write a
 `flake.nix` and define a development shell that includes Python. We'll
@@ -34,31 +48,22 @@ packages you need), and you want to experiment a bit first.
 
 The command to enter a temporary shell is
 
-`nix-shell -p __packages__`
+`nix shell -p __installables__`
 
-If there are multiple packages, they should be separated by spaces.
-
-[NOTE]
-====
-The command used here is `nix-shell` with a hyphen, not `nix shell`
-with a space; those are two different commands. In fact there are
-hyphenated and non-hyphenated versions of many Nix commands, and yes,
-it's confusing. The non-hyphenated commands were introduced when support
-for flakes was added to Nix. I predict that eventually all hyphenated
-commands will be replaced with non-hyphenated versions. Until then, a
-useful rule of thumb is that non-hyphenated commands are for for working
-directly with flakes; hyphenated commands are for everything else.
-====
+Where __installables__ are flakes and other types of packages that you need.
+(You can learn more about these in the
+https://nix.dev/manual/nix/stable/command-ref/new-cli/nix#installables[Nix manual].)
 
 Let's enter a shell with Python so we can test the program.
 
+[#python-nix-shell]
 ....
-$# echo '$ nix-shell -p python3'
-$# nix-shell -p python3 --command sh
+$# echo '$ nix shell nixpkgs#python3'
+$# nix shell nixpkgs#python3 --command sh
 $ python hello.py
 ....
 
-== A Python builder
+== Configuring setuptools
 
 Next, create a Python script to build the package. We'll use Python's
 setuptools, but you can use other build tools. For more information on
@@ -78,9 +83,23 @@ $ curl https://codeberg.org/mhwombat/hello-flake-python/raw/branch/main/setup.py
 $# cat setup.py
 ....
 
-We won't write `flake.nix` just yet. First we'll try building the
-package manually.
+== Building the program manually (optional)
 
+[NOTE]
+====
+In this section you will learn how to do some development tasks manually, the "hard" way.
+This can help you understand the distinction between Nix's role and
+the Python build system you've chosen.
+Also, if you have a build problem but you're not sure if the fault is in
+your flake definition or some other configuration file,
+these commands can help you narrow it down.
+But you may wish to skip to the <<python-flake,next section>>
+and come back here later.
+====
+
+We won't write `flake.nix` just yet.
+First we'll try building the package manually.
+(If you didn't run the `nix shell` command from <<python-nix-shell,earlier>>, do so now.)
 ....
 $ python -m build
 ....
@@ -99,8 +118,9 @@ $# nix-shell -p "python3.withPackages (ps: with ps; [ build ])" --command sh
 
 Note that we're now inside a temporary shell inside the previous
 temporary shell! To get back to the original shell, we have to `exit`
-twice. Alternatively, we could have done `exit` followed by the
-`nix-shell` command.
+twice.
+Alternatively, we could have done `exit` followed by the
+second `nix-shell` command.
 
 ....
 $# echo '$ python -m build'
@@ -109,11 +129,12 @@ $# python -m build > /dev/null 2>&1
 
 After a lot of output messages, the build succeeds.
 
+[#python-flake]
 == The Nix flake
 
-Now we should write `flake.nix`. We already know how to write most of
-the flake from the examples we did earlier. The two parts that will be
-different are the development shell and the package builder.
+Now we should write `flake.nix`.
+We already know how to write most of the flake from the examples we did earlier.
+The two parts that will be different are the development shell and the package builder.
 
 Let's start with the development shell. It seems logical to write
 something like the following.
@@ -172,10 +193,12 @@ $ curl https://codeberg.org/mhwombat/hello-flake-python/raw/branch/main/flake.ni
 $# cat flake.nix
 ....
 
+== Building the program
+
 Let's try out the new flake.
 
 ....
-$ nix run
+$ nix build
 ....
 
 Why can't it find `flake.nix`? Nix flakes only "`see`" files that are
@@ -184,13 +207,28 @@ repo before building or running the flake.
 
 ....
 $ git add flake.nix setup.py hello.py
+$ nix build
+....
+
+We'll deal with those warnings later.
+The important thing for now is that the build succeeded.
+
+== Running the program
+
+Now we can run the program.
+
+....
 $ nix run
 ....
 
+By the way, we didn't need to do `nix build` earlier.
+The `nix run` command will first build the program for us if needed.
+
 We'd like to share this package with others, but first we should do some
-cleanup. When the package was built (automatically by the `nix run`
-command), it created a `flake.lock` file. We need to add this to the
-repo, and commit all important files.
+cleanup.
+It's time to deal with those warnings.
+When the package was built, Nix created a `flake.lock` file.
+We need to add this to the repo, and commit all important files.
 
 ....
 $ git add flake.lock