diff --git a/src/getting-started.md b/src/getting-started.md index d1d3611..861dd03 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -1,152 +1,121 @@ # Getting Started -Labwc is designed to be easy to get started with. +## Introduction -To use the compositor for the first time, there is no need for configuration -files, theme files or even a session file. It should be enough to simply run -the labwc binary from a TTY or Wayland/X11 session. +If you are coming to labwc for the first time, this is the page to read. Should +you get stuck, do reach out on the [IRC Channel] or [Github Discussions]. -If labwc is not packaged by your OS/distribution of choice, it is quite easy -to build (which should take no more than a few seconds) and run from the build -directory.[^1] - -[^1]: The compositor works fine without doing a system-wide installation, but - just be aware that you will not get localized (translated to local - language) window context menus, nor will you get a system-wide .desktop - file where most display managers look for them (if you use one of them). +[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc +[Github Discussions]: https://github.com/labwc/labwc/discussions -The first time you run labwc, you'll be greeted by a blank screen. If you click -on the desktop you will see your root-menu containing 'Reconfigure' and 'Exit'. -Although this initial appearance is minimalist and sparse, it is easy to get -started. +## Context -Before doing any configuration, you can start labwc with the following command -to start an application (alacritty is used in the example, but it could of -course be any application): +Labwc is a system level software component for which the entry barrier is +higher compared with that of many user applications. It can be perceived as +difficult to set up due to the need for manual configuration and because it is +a base component upon which Desktop Environments can be built which means that +there are many ways in which it can be used and that work is required to get +the best out of it. But fret not, with a small amount of work some very +creative experiences will be opened up that will most likely be worth the +effort. -``` -labwc -s alacritty -``` +Pre-configured [Desktop Environments] exist using `labwc` as the compositor, +but in this document you will be guided to start the compositor without any +such setup. -Alternatively, if you have bemenu installed, you can use the default keybind -Alt-F3 to launch applications. +[Desktop Environments]: links.html#desktops - +## Installation -# Configuration +Install `labwc` with your package manager and come back here when done. -User config files are located at `${XDG_CONFIG_HOME:-$HOME/.config/labwc/}` -(usually `~/.config/labwc/`) with the following five files being used: -[rc.xml], [menu.xml], [autostart], [environment] and [themerc-override]. +Also install `alacritty` (a terminal emulator which is available in most +distros' repositories). There is of course nothing forcing you to use +`alacritty` but it is likely to be useful the first time the start the +compositor. -The example [rc.xml] has been kept simple. For all options and default values, -see [rc.xml.all] +## Launching -For full details on configuration options, see the man pages: -[labwc(1)], [labwc-config(5)], [labwc-theme(5)], [labwc-actions(5)] and -[labwc-menu(5)]. +Launch labwc by typing `labwc` in your terminal. Some Display Managers (like +`SDDM` or `GDM`) will show labwc, so you can also start from there. -Run `labwc --reconfigure` to reload configuration and theme files. +> TECHNICAL NOTE: labwc can be started from a TTY or nested in a Wayland/X11 +> session. -Your OS/Distribution of choice may include these example configuration files in -`/usr/share/doc/labwc/` or similar. If not, you could download them with: +If you start `labwc` with no prior configuration you will be greeted by a blank +screen. If you click on the desktop you will see your root-menu containing only +'Reconfigure' and 'Exit' (and 'Terminal' from version 0.9.0 onwards). Do not be +put off by this sparse appearance. There is a lot more to this compositor than +first meets the eye. -```bash -mkdir -p ~/.config/labwc -wget https://raw.githubusercontent.com/labwc/labwc/master/docs/environment -O ~/.config/labwc/environment -wget https://raw.githubusercontent.com/labwc/labwc/master/docs/autostart -O ~/.config/labwc/autostart -wget https://raw.githubusercontent.com/labwc/labwc/master/docs/menu.xml -O ~/.config/labwc/menu.xml -wget https://raw.githubusercontent.com/labwc/labwc/master/docs/rc.xml -O ~/.config/labwc/rc.xml -``` +You can start a terminal by pressing `Super + Return`. -> **_NOTE:_** Before using these configuration files, please read them through -> and modify the content to suit your specific needs. + -For more information about each configuration file and to help create a setup -that work for you, please read through the sections below. +# Configuration -If you get stuck, do reach out on the [IRC Channel] or [Github Discussions]. +Configuration files are located in `$HOME/.config/labwc/` -[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml -[rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all -[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml -[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart -[environment]: https://github.com/labwc/labwc/blob/master/docs/environment -[themerc-override]: https://github.com/labwc/labwc/blob/master/docs/themerc -[labwc(1)]: https://labwc.github.io/labwc.1.html -[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html -[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html -[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html -[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html -[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html -[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc -[Github Discussions]: https://github.com/labwc/labwc/discussions +In this guide we are going to cover some common setup steps which will give you +a good feel for the four most important configuration files which are: +[environment], [rc.xml], [autostart] and [menu.xml]. -## Step 1 - Set your keyboard layout +Whenever a configuration or theme file has been changed, the command `labwc +--reconfigure` has be run for the settings to take affect. With additions to +`autostart` you will need to re-start the compositor. -Set the environment variable `XKB_DEFAULT_LAYOUT` with your country code. +It is generally recommended not to copy the example configuration files, but to +build them from scratch. -For example to start with Swedish keyboard layout, run +## Step 1 - Set your keyboard layout -``` -XKB_DEFAULT_LAYOUT=se labwc -``` +Set the environment variable `XKB_DEFAULT_LAYOUT` with your country code in +`~/.config/labwc/environment`. -Or simply add this line to `~/.config/labwc/environment` +For example to use a Swedish keyboard layout, add this line: ``` XKB_DEFAULT_LAYOUT=se ``` -If you are unsure what your country code is, refer to the 'layout' section of -`/usr/share/X11/xkb/rules/evdev.lst` +If you are unsure what your country code is, use the website +[xkeyboard-config.freedesktop.org] or search the 'layout' section of your +local copy of `evdev.lst` which is typically located at +`/usr/share/X11/xkb/rules/evdev.lst`. -See further details, see [docs/environment] and [xkeyboard-config(7)]. +See further details, see [environment] and [xkeyboard-config(7)]. +[xkeyboard-config.freedesktop.org]: https://xkeyboard-config.freedesktop.org/layouts/gallery [xkeyboard-config(7)]: https://manpages.debian.org/testing/xkb-data/xkeyboard-config.7.en.html -## Step 2 - Add some items to the root-menu - -Create a `~/.config/labwc/menu.xml` to hand-craft a menu. See [docs/menu.xml] -for inspiration, or use the simple example below - -``` - - - - - - - - - - -``` - -See [integration#menu-generators] for ideas on how to automatically create -menu.xml files. +## Step 2 - Set some keybinds -## Step 3 - Set a shortcut to a launcher - -If you want to bind a key-combination to a launcher such as rofi or wofi, or -simply a terminal, create a configuration file `~/.config/labwc/rc.xml` and add -a `` entry as shown below. In this example `Super-d` is bound to the -terminal sakura: +If you want to bind a key-combination to an application like a launcher or +terminal, create a configuration file `~/.config/labwc/rc.xml` and add a +`` section as shown below. ``` - - - + + + + + + + - ``` -See [docs/rc.xml.all] for all available configuration options. +> TECHNICAL NOTE: The `` element includes all the built-in keybinds +> as described [here]. + +[here]: https://labwc.github.io/labwc-config.5.html#entry_keyboard_default + +See [rc.xml] for all available configuration options. To figure out the name of a key, you can use either xev (widely available, runs via xwayland) or [wev]. Alternatively, search for keysym names directly in @@ -155,46 +124,75 @@ runs via xwayland) or [wev]. Alternatively, search for keysym names directly in [wev]: https://git.sr.ht/~sircmpwn/wev [xkbcommon-keysyms.h]: https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h -## Step 4 - Start a background-image client and a panel +## Step 3 - Use a wallpaper and a panel + +We recommend using `swaybg` for setting a background image or color. You can of +course run `swaybg` directly from a launcher or panel, but for persistence add +the example line below to `~/.config/labwc/autostart` + +``` +swaybg -c '#334455' & +``` -To use a background-color/image client or a panel, simply add the command -to `~/.config/labwc/autostart`. See example below for using swaybg and waybar: +...or for an image try something like this: ``` -swaybg -i foo.png >/dev/null 2>&1 & -waybar >/dev/null 2>&1 & +swaybg -i ~/Pictures/wallpaper.png & ``` -The `>/dev/null 2>&1` is simply there to hide the logging. -Don't forget the `&` at the end otherwise the compositor will get stuck on that -line. +> IMPORTANT: The `&` at the end is needed to prevent the compositor getting +> stuck on that line. + +There are many widely packaged bars and panels that can be used with `labwc`, +for example `xfce4-panel`, `lxqt-panel`, `waybar` and `sfwbar`. Just take a +pick and add one to your `~/.config/labwc/autostart` like this: + +``` +xfce4-panel & +``` -See further examples in [docs/autostart] +See further examples in [autostart] -## Step 5 - install some themes for server-side-decorations +## Step 4 - Build a root-menu -Some commonly packaged themes support openbox (and therefore labwc) out of the -box, for example `Numix` and `Adapta`. +Whether or not you take this step really comes down to how you want to use the +compositor. For example, if you prefer to use a desktop client like `xfdesktop` +or `pcmanfm-qt --desktop` which provide their own root menus. -Install a theme and set it in rc.xml: +To handcraft a menu, create a `~/.config/labwc/menu.xml` and populate with +your favourite applications as in the example below: ``` - - Numix - + + + + + + + + + ``` -To just use the current GTK theme, you can use [labwc-gtktheme] +A lot can be done with the compositor menu. See [integration#menu-generators] +and [menu.xml] for ideas on how to automatically create menu.xml files as well +as creating pipemenus. Refer to the [man pages] for full documentation. Enjoy! +[labwc(1)]: https://labwc.github.io/labwc.1.html +[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html +[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html +[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html +[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html +[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html + +[environment]: https://github.com/labwc/labwc/blob/master/docs/environment +[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all +[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart +[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml -[docs/environment]: https://github.com/labwc/labwc/blob/master/docs/environment -[docs/menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml [integration#menu-generators]: https://labwc.github.io/integration.html#menu-generators -[docs/rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all -[docs/autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart -[labwc-gtktheme]: https://github.com/johanmalm/labwc-gtktheme [man pages]: manual.html diff --git a/src/links.md b/src/links.md index 43b1219..a79a06c 100644 --- a/src/links.md +++ b/src/links.md @@ -1,5 +1,15 @@ # Links +## Desktops + +- [Opensuse with Xfce](https://news.opensuse.org/2025/08/04/leap-16-rc/) +- [Raspberry Pi](https://www.raspberrypi.com/news/a-new-release-of-raspberry-pi-os/) +- [LXQt](https://lxqt-project.org/screenshots/labwc/) +- [LXQt on Arch Linux](https://archlinux.org/packages/?name=lxqt-wayland-session) +- [Mabox](https://forum.maboxlinux.org/t/labwc-in-mabox-status/2138) +- [Puppy Linux](https://vanilla-dpup.github.io/) +- [TrixiePup64 Wayland 11.0.0 Beta-2](https://forum.puppylinux.com/viewtopic.php?t=14554) + ## Openbox - [redtide-openbox-wiki] - A clone of the openbox wiki @@ -45,3 +55,38 @@ [randfall]: https://gitlab.freedesktop.org/vyivel/randfall/ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+