Fill out help files, change storepath into storelist

20 files changed, 152 insertions, 44 deletions

diff --git a/COPYING b/COPYING
index 7640bed..9b497a1 100644
--- a/COPYING
+++ b/COPYING
@@ -1,4 +1,4 @@
-Copyright (c) 2018-2025 Laurent Bercot <ska-skaware@skarnet.org>
+Copyright (c) 2018-2026 Laurent Bercot <ska-skaware@skarnet.org>
 
 Permission to use, copy, modify, and distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
diff --git a/configure b/configure
index 3213533..1b19145 100755
--- a/configure
+++ b/configure
@@ -58,7 +58,7 @@ Optional features:
   --enable-util-linux           use util-linux functionality [disabled]
 
   --with-conf-file=FILE         default configuration file for s6 command [SYSCONFDIR/s6-frontend.conf]
-  --with-store-path=PATH        path to service stores [PREFIX/share/s6-frontend/s6-rc/sources:SYSCONFDIR/s6-frontend/s6-rc/sources]
+  --with-store-list=LIST        list of service stores [PREFIX/share/s6-frontend/s6-rc/sources:SYSCONFDIR/s6-frontend/s6-rc/sources]
   --with-default-bundle=NAME    name of the bundle started at boot [s6-rc default: default]
 
 EOF
@@ -186,7 +186,7 @@ repodir=
 bootdb=
 stmpdir=/run/s6-frontend
 conffile='$sysconfdir/s6-frontend.conf'
-storepath='$prefix/share/s6-rc/sources:$sysconfdir/s6-rc/sources'
+storelist='$prefix/share/s6-frontend/s6-rc/sources:$sysconfdir/s6-frontend/s6-rc/sources'
 defbundle=
 
 usensss=false
@@ -235,7 +235,7 @@ for arg ; do
     --bootdb=*) bootdb=${arg#*=} ;;
     --stmpdir=*) stmpdir=${arg#*=} ;;
     --with-conf-file=*) conffile=${arg#*=} ;;
-    --with-store-path=*) storepath=${arg#*=} ;;
+    --with-store-list=*) storelist=${arg#*=} ;;
     --with-default-bundle=*) defbundle=${arg#*=} ;;
     --enable-nsss|--enable-nsss=yes) usensss=true ;;
     --disable-nsss|--enable-nsss=no) usensss=false ;;
@@ -271,7 +271,7 @@ fi
 
 # Expand installation directories
 stripdir prefix
-for i in exec_prefix dynlibdir libexecdir bindir libdir includedir sysconfdir pkgconfdir sysdeps sproot stmpdir conffile storepath ; do
+for i in exec_prefix dynlibdir libexecdir bindir libdir includedir sysconfdir pkgconfdir sysdeps sproot stmpdir conffile storelist ; do
   eval tmp=\${$i}
   eval $i=$tmp
   stripdir $i
@@ -553,7 +553,7 @@ echo "LIVEDIR := $livedir"
 echo "REPODIR := $repodir"
 echo "BOOTDB := $bootdb"
 echo "STMPDIR := $stmpdir"
-echo "STOREPATH := $storepath"
+echo "STORELIST := $storelist"
 
 if $usensss ; then
   echo "LIBNSSS := -lnsss"
@@ -665,8 +665,8 @@ echo "#define ${package_macro_name}_STMPDIR \"$stmpdir\""
 echo "#undef ${package_macro_name}_CONF"
 echo "#define ${package_macro_name}_CONF \"$conffile\""
 
-echo "#undef ${package_macro_name}_STOREPATH"
-echo "#define ${package_macro_name}_STOREPATH \"$storepath\""
+echo "#undef ${package_macro_name}_STORELIST"
+echo "#define ${package_macro_name}_STORELIST \"$storelist\""
 echo
 echo "#endif"
 exec 1>&3 3>&-
diff --git a/package/configure-snippets/configure_case_lines b/package/configure-snippets/configure_case_lines
index 70af1f9..94c1202 100644
--- a/package/configure-snippets/configure_case_lines
+++ b/package/configure-snippets/configure_case_lines
@@ -4,7 +4,7 @@
     --bootdb=*) bootdb=${arg#*=} ;;
     --stmpdir=*) stmpdir=${arg#*=} ;;
     --with-conf-file=*) conffile=${arg#*=} ;;
-    --with-store-path=*) storepath=${arg#*=} ;;
+    --with-store-list=*) storelist=${arg#*=} ;;
     --with-default-bundle=*) defbundle=${arg#*=} ;;
     --enable-nsss|--enable-nsss=yes) usensss=true ;;
     --disable-nsss|--enable-nsss=no) usensss=false ;;
diff --git a/package/configure-snippets/configure_expand_dirs b/package/configure-snippets/configure_expand_dirs
index 7b2c617..d4eff64 100644
--- a/package/configure-snippets/configure_expand_dirs
+++ b/package/configure-snippets/configure_expand_dirs
@@ -1 +1 @@
-stmpdir conffile storepath
+stmpdir conffile storelist
diff --git a/package/configure-snippets/configure_generate_configh b/package/configure-snippets/configure_generate_configh
index 837923d..6fcb60a 100644
--- a/package/configure-snippets/configure_generate_configh
+++ b/package/configure-snippets/configure_generate_configh
@@ -70,5 +70,5 @@ echo "#define ${package_macro_name}_STMPDIR \"$stmpdir\""
 echo "#undef ${package_macro_name}_CONF"
 echo "#define ${package_macro_name}_CONF \"$conffile\""
 
-echo "#undef ${package_macro_name}_STOREPATH"
-echo "#define ${package_macro_name}_STOREPATH \"$storepath\""
+echo "#undef ${package_macro_name}_STORELIST"
+echo "#define ${package_macro_name}_STORELIST \"$storelist\""
diff --git a/package/configure-snippets/configure_generate_make b/package/configure-snippets/configure_generate_make
index da6004c..1fa9ea2 100644
--- a/package/configure-snippets/configure_generate_make
+++ b/package/configure-snippets/configure_generate_make
@@ -3,7 +3,7 @@ echo "LIVEDIR := $livedir"
 echo "REPODIR := $repodir"
 echo "BOOTDB := $bootdb"
 echo "STMPDIR := $stmpdir"
-echo "STOREPATH := $storepath"
+echo "STORELIST := $storelist"
 
 if $usensss ; then
   echo "LIBNSSS := -lnsss"
diff --git a/package/configure-snippets/configure_help_options b/package/configure-snippets/configure_help_options
index ed0f440..c36b3ed 100644
--- a/package/configure-snippets/configure_help_options
+++ b/package/configure-snippets/configure_help_options
@@ -3,6 +3,6 @@
   --enable-util-linux           use util-linux functionality [disabled]
 
   --with-conf-file=FILE         default configuration file for s6 command [SYSCONFDIR/s6-frontend.conf]
-  --with-store-path=PATH        path to service stores [PREFIX/share/s6-frontend/s6-rc/sources:SYSCONFDIR/s6-frontend/s6-rc/sources]
+  --with-store-list=LIST        list of service stores [PREFIX/share/s6-frontend/s6-rc/sources:SYSCONFDIR/s6-frontend/s6-rc/sources]
   --with-default-bundle=NAME    name of the bundle started at boot [s6-rc default: default]
 
diff --git a/package/configure-snippets/configure_init_vars b/package/configure-snippets/configure_init_vars
index ef66101..52ffdfc 100644
--- a/package/configure-snippets/configure_init_vars
+++ b/package/configure-snippets/configure_init_vars
@@ -4,7 +4,7 @@ repodir=
 bootdb=
 stmpdir=/run/s6-frontend
 conffile='$sysconfdir/s6-frontend.conf'
-storepath='$prefix/share/s6-rc/sources:$sysconfdir/s6-rc/sources'
+storelist='$prefix/share/s6-frontend/s6-rc/sources:$sysconfdir/s6-frontend/s6-rc/sources'
 defbundle=
 
 usensss=false
diff --git a/src/include-local/s6f.h b/src/include-local/s6f.h
index fbeab7e..90d7565 100644
--- a/src/include-local/s6f.h
+++ b/src/include-local/s6f.h
@@ -15,6 +15,7 @@ struct s6f_confdirs_s
   char const *repo ;  /* $XDG_DATA_HOME/s6-frontend/repository */
   char const *boot ;  /* $XDG_CONFIG_HOME/s6-rc/compiled/current */
   char const *stmp ;  /* $XDG_RUNTIME_DIR/s6-frontend */
+  char const *stol ;  /* $XDG_CONFIG_HOME/s6-rc/sources */
 } ;
 
 extern int s6f_confdir_open (char const *, int) ;
diff --git a/src/libs6f/s6f_user_get_confdirs.c b/src/libs6f/s6f_user_get_confdirs.c
index 5617bf9..6e79a7a 100644
--- a/src/libs6f/s6f_user_get_confdirs.c
+++ b/src/libs6f/s6f_user_get_confdirs.c
@@ -16,7 +16,7 @@
 
 void s6f_user_get_confdirs (s6f_confdirs *dirs, stralloc *storage)
 {
-  size_t scanpos, livepos, repopos, bootpos, stmppos ;
+  size_t scanpos, livepos, repopos, bootpos, stmppos, stolpos ;
   size_t homelen = 0 ;
   struct passwd *pw = 0 ;
   char const *home = 0 ;
@@ -76,6 +76,11 @@ void s6f_user_get_confdirs (s6f_confdirs *dirs, stralloc *storage)
    || !stralloc_cats(storage, "/s6-frontend")
    || !stralloc_0(storage)) dienomem() ;
 
+  stolpos = storage->len ;
+  if (!(datahome ? stralloc_cats(storage, datahome) : stralloc_cats(storage, home) && stralloc_cats(storage, "/.local/share"))
+   || !stralloc_cats(storage, "/s6-frontend/s6-rc/sources")
+   || !stralloc_0(storage)) dienomem() ;
+
  /* Don't add to storage past this point */
 
   dirs->scan = storage->s + scanpos ;
@@ -83,4 +88,5 @@ void s6f_user_get_confdirs (s6f_confdirs *dirs, stralloc *storage)
   dirs->repo = storage->s + repopos ;
   dirs->boot = storage->s + bootpos ;
   dirs->stmp = storage->s + stmppos ;
+  dirs->stol = storage->s + stolpos ;
 }
diff --git a/src/s6-frontend/live.help.txt b/src/s6-frontend/live.help.txt
index 6af99c8..acb383b 100644
--- a/src/s6-frontend/live.help.txt
+++ b/src/s6-frontend/live.help.txt
@@ -1 +1,28 @@
-This is the live help message.
+Usage: s6 live subcommand [ options ] services...
+
+Subcommands:
+  help			this message
+  status		read the status of a list of services
+  start			start a service (with all its dependencies)
+  stop			stop a service (and everything depending on it)
+  restart		stop, then start, a service, with dependencies
+  install		install the latest committed service set
+  start-everything	start all the services enabled at boot
+  stop-everything	stop all the non-essential services
+
+s6 live status options: none
+
+s6 live start, s6 live stop, s6 live restart, s6 live stop-everything options:
+  -n		--dry-run		only show what would be done, don't do it
+  -t TIMEOUT	--timeout=TIMEOUT	if not done after TIMEOUT milliseconds, abort
+
+s6 live install options:
+  -b		--block			wait rather than fail on contention
+  -K		--keep-old		keep the old db and write its path to stdout
+  -f FILE	--conversion-file=FILE	use a conversion file from current to new set
+
+s6 live start-everything options:
+  -n		--dry-run		only show what would be done, don't do it
+  -t TIMEOUT	--timeout=TIMEOUT	if not done after TIMEOUT milliseconds, abort
+  -D BUN	--default-bundle=BUN	name of the bundle to start
+
diff --git a/src/s6-frontend/live_stop_everything.c b/src/s6-frontend/live_stop_everything.c
index 8dc2ae3..7d98c70 100644
--- a/src/s6-frontend/live_stop_everything.c
+++ b/src/s6-frontend/live_stop_everything.c
@@ -14,7 +14,6 @@ enum golb_e
 enum gola_e
 {
   GOLA_TIMEOUT,
-  GOLA_DEFBUNDLE,
   GOLA_N
 } ;
 
diff --git a/src/s6-frontend/main.help.txt b/src/s6-frontend/main.help.txt
index c769504..9adabfe 100644
--- a/src/s6-frontend/main.help.txt
+++ b/src/s6-frontend/main.help.txt
@@ -1,34 +1,29 @@
-Usage: s6 [ global options ] command subcommand [ subcommand options ] [ arguments... ]
+Usage: s6 [ global_options... ] command subcommand [ subcommand_options... ] [ args... ]
 
 For details about a command and its options, try: s6 command help (e.g.: s6 live help)
 
-
 Commands:
-
   help		this message
   version	print the version of this package
-
   system	boot and shutdown the system
   live		start and stop services and their dependencies
   process	control individual long-running processes
-
   set		manipulate sets of services (offline, to later install them live)
   repository	manipulate the service repository itself
 
-
 Global options:
-
   -h		--help			equivalent to "s6 help"
   -V		--version		equivalent to "s6 version"
 
 		--color=yes|no|auto	display fancy or boring-but-parsable text.
 					auto is the default: fancy if in a terminal.
 
-  These options override the values set in s6-frontend.conf:
+ These options override the values set in s6-frontend.conf:
   -v V		--verbosity=V		verbosity (0 is terse, 1 is normal/default, more is verbose)
   -s SCANDIR	--scandir=SCANDIR	where s6-svscan is running
   -l LIVEDIR	--livedir=LIVEDIR	s6-rc live directory
   -r REPODIR	--repodir=REPODIR	s6-rc service set repository
   -c BOOTDB	--bootdb=BOOTDB		live database the system is booting on
 		--stmpdir=STMPDIR	root-only temporary directory
+		--storelist=LIST	list of service stores
 
diff --git a/src/s6-frontend/process.help.txt b/src/s6-frontend/process.help.txt
index 0b5208b..5c1f9db 100644
--- a/src/s6-frontend/process.help.txt
+++ b/src/s6-frontend/process.help.txt
@@ -1,18 +1,19 @@
-Usage: s6 process subcommand [ options ] services...
+Usage: s6 process subcommand [ options ] longruns...
 
-Subcommands:
+ Send commands to *processes* at the s6 supervision level.
+(supervised long-running processes only - not services at the
+s6-rc level. This is useful e.g. to restart a process without
+stopping then starting things depending on it.)
 
+Subcommands:
   help		this message
-
   start		start a supervised process without impacting its official state
   stop		stop a supervised process without impacting its official state
   restart	restart a supervised process
   kill		send a signal to a supervised process
   status	read the status of a supervised process
 
-
 s6 process start and s6 process stop options:
-
   -P		--no-permanent		don't override the official state if the daemon dies
 					(i.e. if the service manager says the service should be
 					down, do not restart the daemon; if it says the service
@@ -23,18 +24,21 @@ s6 process start and s6 process stop options:
   -w		--wait			only exit once the daemon is ready or confirmed dead
   -t TIMEOUT	--timeout=TIMEOUT	if -w: give up if not ready after TIMEOUT milliseconds
 
-
 s6 process restart options:
-
   -W		--no-wait		exit without waiting for service readiness
   -w		--wait			only exit once the daemon is ready again
   -t TIMEOUT	--timeout=TIMEOUT	if -w: give up if not ready after TIMEOUT milliseconds
 
-
 s6 process kill options:
-
   -W		--no-wait		exit without waiting for service readiness
   -w		--wait			only exit once the daemon is ready again, if applicable
   -t TIMEOUT	--timeout=TIMEOUT	if -w: give up if not ready after TIMEOUT milliseconds
   -s SIGNAL	--signal=SIGNAL		send signal SIGNAL rather than the default (prob. SIGTERM)
 
+s6 process status options:
+
+  -L		--without-logs		only list the status of longruns given as arguments (default)
+  -l		--with-logs		also list status for service/log. This has no effect
+					on services that have loggers declared in s6-rc, for these
+					you need to list the logger explicitly.
+
diff --git a/src/s6-frontend/repository.help.txt b/src/s6-frontend/repository.help.txt
index 91e14f7..7a07296 100644
--- a/src/s6-frontend/repository.help.txt
+++ b/src/s6-frontend/repository.help.txt
@@ -1 +1,18 @@
-This is the repository help message.
+Usage: s6 repository subcommand [ options ]
+
+Subcommands:
+  help		this message
+  init		initialize a service repository
+  sync		synchronize repository with stores
+  list		list names of saved service sets
+
+s6 repository init options:
+  -f		--force			Overwrite existing repository
+  -U		--update-stores		Update existing repository with new stores
+  -h USER	--fdholder-user		Set USER as reference fdholder owner
+
+s6 repository sync options:
+  -h USER	--fdholder-user		Set USER as reference fdholder owner
+
+s6 repository list options: none
+
diff --git a/src/s6-frontend/repository_init.c b/src/s6-frontend/repository_init.c
index e26c816..548c1fd 100644
--- a/src/s6-frontend/repository_init.c
+++ b/src/s6-frontend/repository_init.c
@@ -24,7 +24,6 @@ enum golb_e
 enum gola_e
 {
   GOLA_FDHUSER,
-  GOLA_STOREPATH,
   GOLA_N
 } ;
 
@@ -38,7 +37,6 @@ void repository_init (char const *const *argv)
   static gol_arg const rgola[] =
   {
     { .so = 'h', .lo = "fdholder-user", .i = GOLA_FDHUSER },
-    { .so = 'p', .lo = "store-path", .i = GOLA_STOREPATH },
   } ;
   uint64_t wgolb = 0 ;
   unsigned int m = 0 ;
@@ -47,15 +45,14 @@ void repository_init (char const *const *argv)
   size_t len ;
   char fmtv[UINT_FMT] ;
 
-  wgola[GOLA_STOREPATH] = S6_FRONTEND_STOREPATH ;
   argv += GOL_argv(argv, rgolb, rgola, &wgolb, wgola) ;
 
-  len = strlen(wgola[GOLA_STOREPATH]) ;
+  len = strlen(g->dirs.stol) ;
   char storage[len+1] ;
   for (size_t i = 0 ; i < len ; i++)
   {
-    if (wgola[GOLA_STOREPATH][i] == ':') { n++ ; storage[i] = 0 ; }
-    else storage[i] = wgola[GOLA_STOREPATH][i] ;
+    if (g->dirs.stol[i] == ':') { n++ ; storage[i] = 0 ; }
+    else storage[i] = g->dirs.stol[i] ;
   }
   if (storage[len-1]) { n++ ; storage[len] = 0 ; }
 
diff --git a/src/s6-frontend/s6-frontend-internal.h b/src/s6-frontend/s6-frontend-internal.h
index c7ee0e2..ddd3b69 100644
--- a/src/s6-frontend/s6-frontend-internal.h
+++ b/src/s6-frontend/s6-frontend-internal.h
@@ -121,6 +121,7 @@ struct global_s
     .repo = S6_FRONTEND_REPODIR, \
     .boot = S6_FRONTEND_BOOTDB, \
     .stmp = S6_FRONTEND_STMPDIR, \
+    .stol = S6_FRONTEND_STORELIST, \
   }, \
   .userstorage = STRALLOC_ZERO, \
   .isuser = 0, \
diff --git a/src/s6-frontend/s6-frontend.c b/src/s6-frontend/s6-frontend.c
index 2b78dbf..98314bf 100644
--- a/src/s6-frontend/s6-frontend.c
+++ b/src/s6-frontend/s6-frontend.c
@@ -40,6 +40,7 @@ enum gola_e
   GOLA_REPODIR,
   GOLA_BOOTDB,
   GOLA_STMPDIR,
+  GOLA_STORELIST,
   GOLA_VERBOSITY,
   GOLA_COLOR,
   GOLA_N
@@ -62,6 +63,7 @@ int main (int argc, char const *const *argv)
     { .so = 'r', .lo = "repodir", .i = GOLA_REPODIR },
     { .so = 'c', .lo = "bootdb", .i = GOLA_BOOTDB },
     { .so = 0,   .lo = "stmpdir", .i = GOLA_STMPDIR },
+    { .so = 0,   .lo = "storelist", .i = GOLA_STORELIST },
     { .so = 'v', .lo = "verbosity", .i = GOLA_VERBOSITY },
     { .so = 0,   .lo = "color", .i = GOLA_COLOR },
   } ;
@@ -87,6 +89,7 @@ int main (int argc, char const *const *argv)
     [GOLA_REPODIR] = getenv("repodir"),
     [GOLA_BOOTDB] = getenv("bootdb"),
     [GOLA_STMPDIR] = getenv("stmpdir"),
+    [GOLA_STORELIST] = getenv("storelist"),
     [GOLA_VERBOSITY] = getenv("verbosity"),
     [GOLA_COLOR] = 0
   } ;
@@ -108,6 +111,7 @@ int main (int argc, char const *const *argv)
   if (wgola[GOLA_REPODIR]) g->dirs.repo = wgola[GOLA_REPODIR] ;
   if (wgola[GOLA_BOOTDB]) g->dirs.boot = wgola[GOLA_BOOTDB] ;
   if (wgola[GOLA_STMPDIR]) g->dirs.stmp = wgola[GOLA_STMPDIR] ;
+  if (wgola[GOLA_STORELIST]) g->dirs.stol = wgola[GOLA_STORELIST] ;
 
   {
     int force_color = 0 ;
diff --git a/src/s6-frontend/set.help.txt b/src/s6-frontend/set.help.txt
index 3876309..e998852 100644
--- a/src/s6-frontend/set.help.txt
+++ b/src/s6-frontend/set.help.txt
@@ -1 +1,45 @@
-This is the set help message.
+Usage: s6 set subcommand [ options ] [ arguments... ]
+
+Subcommands:
+  help		this message
+  save		save the current set under a user-provided name
+  load		load a previously saved set
+  list		list services in the working set
+  status	list services in the working set with their sub
+  enable	enable services
+  disable	disable services
+  mask		mask services (hide them from the db entirely)
+  unmask	unmask services (equivalent to "disable")
+  check		check working set and fix inconsistencies
+  commit	commit working set (can then be installed)
+
+
+s6 set save options:
+  -f		--force				overwrite named set if existing
+
+s6 set load options: none
+
+s6 set list options: none
+
+s6 set status options:
+  -E		--with-essentials		show all services, even essential ones (default)
+  -e		--without-essentials		don't show essential services
+
+s6 set enable|disable|mask|unmask options:
+  -f		--ignore-dependencies		only change listed services
+  -n		--dry-run			show what would happen, don't do
+  -I WHAT	--if-dependencies-found=WHAT	WHAT=warn (default) | fail | pull (dependencies will be brought to the same sub)
+
+s6 set check options:
+  -E		--no-force-essential		do not allow manual changes to essential services (default)
+  -e		--force-essential		allow manual changes to essential services
+  -f		--fix				try to fix inconsistencies automatically
+  -d		--down				fix by disabling or masking services if necessary (default)
+  -u		--up				fix by enabling services if necessary
+
+s6 set commit options:
+  -f		--force				compile db even if up-to-date
+  -K		--keep-old			keep old db if any, print its path to stdout
+  -D BUN	--default-bundle=BUN		name of the bundle containing enabled+essential services
+  -h USER	--fdholder-user=USER		user for the s6-fdholderd process (default=root, it's fine)
+
diff --git a/src/s6-frontend/system.help.txt b/src/s6-frontend/system.help.txt
index 3e0af51..0fe4eaa 100644
--- a/src/s6-frontend/system.help.txt
+++ b/src/s6-frontend/system.help.txt
@@ -1 +1,14 @@
-This is the system help message.
+Usage: s6 system subcommand
+
+Subcommands:
+  help		this message
+  boot		initialize the service manager and start default services
+
+ plus, if s6-frontend has been built with s6-linux-init support:
+  halt		halt the system (without powering it off)
+  poweroff	halt the system, powering it off
+  shutdown	synonymous with poweroff
+  reboot	reboot the system
+
+No options.
+