Menu
▾
▴
Tree [c14d52] default tip / History
Read Me
__ ___ __ ___ _____ ___ __ ___ __ _ ___ _ __
\ \ /\ / / '_ ` _ \/ __\ \ / / '_ ` _ \ / _` |/ _ \ '_ \
\ V V /| | | | | \__ \\ V /| | | | | | (_| | __/ | | |
\_/\_/ |_| |_| |_|___/ \_/ |_| |_| |_|\__, |\___|_| |_|
__/ |
|___/
About
-----
wmsvmgen is a menu generator to ease access to storage volumes under the
following window managers :
Fluxbox
Openbox
Window Maker
For each of the target window managers, a menu is generated each time
a (non-filtered) storage volume is inserted, removed, mounted, unmounted.
For each available storage volume, there is a dedicated sub-menu with the
options described below.
Mount
-----
Allows to "mount" a storage volume. Disabled when the storage volume
is (already) mounted.
Unmount
-------
Allows to "unmount" a storage volume. Disabled when the storage volume
is not mounted.
Open
----
Allows to "open" a storage volume in a file manager.
Open Terminal Here
------------------
Allows to "open" a storage volume in a terminal emulator.
Infos
-----
Allows to get informations about a storage volume.
Requirements
------------
wmsvmgem :
* cmake
* libnotify
* lsblk (runtime)
* findmnt (runtime)
* udisksctl (runtime)
wmsvm_util :
* libnotify (runtime)
* yad (runtime)
* udisksctl (runtime)
* a polkit authentication agent (1,2) (runtime)
(1) Needed to access storage volumes for which authentication
is required.
(2) wiki.archlinux.org/index.php/Polkit#Authentication_agents
Incompatibilities
-----------------
wmsvmgen is not compatible with *BSD operating systems.
Installation
------------
To compile wmsvmgen with default settings and install it in /usr/bin,
simply run the following commands :
8<--------------------------------------------------------------------
$ mkdir _build
$ cd _build
$ cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release ..
$ make
$ make install
8<--------------------------------------------------------------------
Note that Native Language Support (NLS) can be disabled by passing
-DENABLE_NLS=OFF to cmake.
Usage
-----
wmsvmgen requires a configuration file that must be specified on the command
line through the option -c|--config like in example below :
8<--------------------------------------------------------------------
$ wmsvmgen --config ~/.wmsvmgen/wmsvmgen.conf
8<--------------------------------------------------------------------
It is highly recommended to start wmsvmgen before starting a window manager,
and, when run at user level, it will be required to terminate it on window
manager exit.
In case of Fluxbox window manager, this can be achieved by modifying the
fluxbox startup script ~/.fluxbox/startup as in example below :
8<--------------------------------------------------------------------
[...]
wmsvmgen --config ~/.wmsvmgen/wmsvmgen.conf &
WMSVMGEN_PID=$!
exec fluxbox &
FLUXBOX_PID=$!
wait $FLUXBOX_PID
kill $WMSVMGEN_PID
8<--------------------------------------------------------------------
wmsvmgen can also be run system-wide with the .rc script rc.wmsvmgen
which is installed in /etc/rc.d and uses the system-wide configuration
/etc/wmsvmgen/wmsvmgen.conf by default.
For instance, to start wmsvmgen at system startup, this script must be run
as below :
8<--------------------------------------------------------------------
$ rc.wmsvmgen start
8<--------------------------------------------------------------------
The configuration used by rc.wmsvmgen can be redefined through the
environment variable WMSVM_CFGFILE like in example below :
8<--------------------------------------------------------------------
$ WMSVM_CFGFILE=/path/to/wmsvmgen.conf rc.wmsvmgen start
8<--------------------------------------------------------------------
By default, rc.wmsvmgen redirect wmsvmgen output into the file
/var/log/wmsvmgen.log. This can be redefined through the environment
variable WMSVM_LOGFILE like in example below :
8<--------------------------------------------------------------------
$ WMSVM_LOGFILE=/path/to/wmsvmgen.log rc.wmsvmgen start
8<--------------------------------------------------------------------
Note that when WMSVM_LOGFILE is set to /dev/null, rc.wmsvmgen starts
wmsvmgen with option --quiet so that wmsmvgen will run silently (only
warnings and errors are printed on stderr).
Configuration File
------------------
The configuration file passed in argument to option -c|--config must be to
plain text format with entries to the format :
property=value
Commented lines, i.e. which start with a # - preceded or not by space(s) -,
are ignored.
Spaces at both side of loaded values are automatically removed.
When there are more than one occurence of a given property, only the first
value is loaded, the others being ignored.
Here is the list of supported properties :
target-window-managers (required)
----------------------
The window-manager(s) for which a storage volumes menu must be generated,
given as a list to the format <wmname>[,<wmname> ...], where wmname can
be :
fluxbox
openbox
windowmaker
output-dir (required)
----------
The destination directory in which the generated menu file(s) should be
placed.
Each generated menu file is named <window-manager>.svmenu, where
<window-manager> is the name of one of the supported window manager
(see property target-window-managers).
only-removable (optional)
--------------
Defines if only the removable storage volumes must be accessible from
the menu.
Can be set to: 1,true,on,yes,0,false,off,no.
empty-menus-on-exit (optional)
-------------------
Defines whether or not the generated menu(s) must be emptied on exit.
Can be set to: 1,true,on,yes,0,false,off,no.
notify-insert-remove (optional)
--------------------
Defines if user must be notified through the desktop notification
service (ex. dunst) when any of the supported storage volumes is
inserted or removed.
Can be set to: 1,true,on,yes,0,false,off,no.
Note that feature may not work when wmsvmgen is executed system-
wide (ie. as root).
exclude-volumes (optional)
---------------
Comma separated list of storage volumes that must be excluded from the
menu. Each item in this list can be :
. a block device (ex. /dev/sda1)
. a label (ex. SYS_PART)
. an uuid (ex. 0C91-F1F0)
force-volumes (optional)
-------------
Comma separated list of storage volumes that must be in the menu regardless
the exclusion list specified by property exclude-volumes and the value of
property only-removable. Each item in this list can be :
. a block device (ex. /dev/sda1)
. a label (ex. SYS_PART)
. an uuid (ex. 0C91-F1F0)
mount-command (required)
-------------
The command(s) to execute when user selects the option "Mount". Any
of the following tags can be part of the commands: %DEV%, %DEV_LABEL%,
%DEV_UUID%
unmount-command (required)
---------------
The command(s) to execute when user selects the option "Unmount". Any
of the following tags can be part of the commands: %DEV%, %DEV_LABEL%,
%DEV_UUID%, %DEV_MPOINT%
open-command (required)
------------
The command(s) to execute when user selects the option "Open". Any of
the following tags can be part of the commands: %DEV%, %DEV_LABEL%,
%DEV_UUID%, %DEV_MPOINT%
open-terminal-command (required)
---------------------
The command(s) to execute when user selects the option "Open Terminal
Here". Any of the following tags can be part of the commands: %DEV%,
%DEV_LABEL%, %DEV_UUID%, %DEV_MPOINT%
infos-command (required)
-------------
The command(s) to execute when user selects the option "Infos". Any of
the following tags can be part of the commands: %DEV%, %DEV_LABEL%,
%DEV_UUID%, %DEV_MPOINT%
Ready-to-use configuration files
--------------------------------
wmsvmgen comes with the ready-to-use configuration files below :
* /usr/doc/wmsvmgen/wmsvmgen-user.conf
Template user configuration file.
* /etc/wmsvmgen/wmsvmgen.conf
system-wide configuration that must be used at system level only, and
which is the default configuration used by the script /etc/rc.d/rc.wmsvmgen.
These configurations :
* respectively define '~/.wmsvmgen' and '/var/lib/wmsvmgen' as the directory
where generated menu file(s) must be placed.
* are designed to only give access to removable storage volumes.
* delegate the execution of commands mount/unmount/... to the script
wmsvm_util which is installed in /usr/bin.
Access storage volumes menu from window managers
------------------------------------------------
To access the storage volumes menu generated for a given window manager,
this one need to be configured beforehand.
The instructions below assumes that generated menu files are stored in
/var/lib/wmsvmgen (output directory defined by the system-wide configuration
/etc/wmsvmgen/wmsvmgen.conf).
1. Fluxbox configuration
---------------------
a. Configuration for an access from root-menu
------------------------------------------
Open the root menu file (~/.fluxbox/menu by default), then, after
the entry "Fluxbox menu", add the following :
8<--------------------------------------------------------------
[submenu] (Storage Volumes)
[include] (/var/lib/wmsvmgen/fluxbox.svmenu)
[end]
8<--------------------------------------------------------------
b. Configuration for an access from a popup-menu
---------------------------------------------
Open the keyboard shortcuts configuration file ~/.fluxbox/keys,
then at the end of this file, add the following :
8<--------------------------------------------------------------
Mod4 m Mod4 v :CustomMenu /var/lib/wmsvmgen/fluxbox.svmenu
8<--------------------------------------------------------------
This allows to access the storage volumes menu with the shortcut
<WinKey> + <M> + <WinKey> + <V>.
c. Configuration for an access from the status bar
-----------------------------------------------
Attention, at the time of writing this documentation, this
configuration requires the development version of Fluxbox,
i.e Fluxbox > 1.3.7.
Open fluxbox resources file ~/.fluxbox/init, then :
* add :
8<----------------------------------------------------------
session.screen0.toolbar.button.stovol.label: Vol.
session.screen0.toolbar.button.stovol.commands: CustomMenu /var/lib/wmsvmgen/fluxbox.svmenu
8<----------------------------------------------------------
* in resource session.screen0.toolbar.tools, add 'button.stovol'.
Note that instead of label 'Vol.', it would be better
to use a symbol character like 'Hot Springs' [1,2]
[1] https://www.compart.com/en/unicode/U+2668
[2] unicode character \342\231\250
2. Openbox configuration
---------------------
To access the storage volumes menu from OpenBox main menu, open
~/.config/openbox/menu.xml, then :
1. Above the line <menu id="root-menu" label="Openbox 3">,
add the following :
8<-------------------------------------------------------------
<menu id="storage-volumes"
label="Storage Volumes"
execute="cat /var/lib/wmsvmgen/openbox.svmenu" />
8<-------------------------------------------------------------
2. Above the line <separator label="System" />, add
the following :
8<-------------------------------------------------------------
<menu id="storage-volumes" />
8<-------------------------------------------------------------
3. Window Maker configuration
--------------------------
To access the storage volumes menu from Window Maker main menu, open
~/GNUstep/Defaults/WMRootMenu, then, before the line ("Exit Window Maker",
EXIT), add the following :
8<-------------------------------------------------------------
("Storage Volumes",OPEN_MENU,/var/lib/wmsvmgen/windowmaker.svmenu")
8<-------------------------------------------------------------
Limitations
-----------
if the menu generated by wmsvmgen is open (in fluxbox for instance) while
a storage volume is mounted/unmounted or a storage device is inserted/removed,
these changes will be accessible/visible only after the menu is closed then
re-opened.
Troubleshooting
---------------
In case of issue with wmsvmgen, rebuild it with debug informations by passing
-DCMAKE_BUILD_TYPE=Debug (or RelWithDebInfo) to cmake, re-run wmsvmgen to
reproduce the issue, then send the system configuration in use, the output
of wmsvmgen, the back/stack trace, if any, and any other informations that
could be useful to solve the issue, at :
<slacker6896@gmail.com>
Known issues
------------
None
Translation
-----------
wmsvmgen
--------
wmsvmgen manual page, and messages printed on STDOUT when running
wmsvmgen (including help page), are translated in French only.
wmsvm_util
----------
The translation of messages specified in wmsvm_util configuration file
are supplied in file(s), stored in /usr/share/wmsvm_util/locale, that
follow the naming convention below :
wmsvm_util-<lang>[_<country>][@modifier].conf
wmsvm_util loads the 1st available translation file according to the
table below :
LC_MESSAGES ! Possible translation files
! in order of matching
---------------------+---------------------------------------------
lang_COUNTRY@MODIFIER! wmsvm_util-lang_COUNTRY@MODIFIER.conf
! wmsvm_util-lang_COUNTRY.conf
! wmsvm_util-lang@MODIFIER.conf
! wmsvm_util-lang.conf
---------------------+---------------------------------------------
lang_COUNTRY ! wmsvm_util-lang_COUNTRY.conf
! wmsvm_util-lang.conf
---------------------+---------------------------------------------
lang@MODIFIER ! wmsvm_util-lang@MODIFIER.conf
! wmsvm_util-lang.conf
---------------------+-----------------------------------------------
lang ! wmsvm_util-lang.conf
Below the progress status of supported locales :
LOCALE ! STATUS ! PROGRESS
----------+---------------+--------------
de ! In progress ! 92% (51/55)
en ! Done ! 100%
es ! In progress ! 92% (51/55)
fr ! Done ! 100%
it ! In progress ! 12% ( 7/55)
nl ! In progress ! 92% (51/55)
pl ! In progress ! 63% ( 7/55)
pt ! In progress ! 90% (50/55)
ru ! In progress ! 65% (36/55)
sv ! In progress ! 12% ( 7/55)
Support of any new locale requires to proceed as below :
1. create the configuration file for the target locale. The
easiest way is to start from a copy of any supported locale,
wmsvm_util-en.conf for instance :
$ cd conf/locale
$ cat wmsvm_util-en.conf wmsvm_util-en_AU.conf
2. Specify the target locale in the header of the configuration
file for that locale.
For instance, in the case of example in (1), at start of file
wmsvm_util-en_AU.conf, it is required to replace :
# wmsvm_util (Language: en)
With :
# wmsvm_util (Language: en_AU)
3. Make translation.
4. in CMakeLists.txt, update the following block accordingly :
# Install translation files for wmsvm_util..
#
set (LANGS de en es fr it nl pl pt ru sv)
5. Rebuild and reinstall wmsvmgen.
Anybody who wants to contribute to translation (or even correction) is
welcome and can contact me at <slacker6896@gmail.com>.
Authors
-------
+ Sébastien Ballet <slacker6896@gmail.com>
License
-------
The source code of this program is governed by the BSD 3-clause license
that can be found in the LICENSE file.
Credits
-------
wmsvmgen logo was generated on patorjk.com/software/taag using font
Doom.
