diff --git a/readme.md b/readme.md index 15cd5ab..095b77f 100644 --- a/readme.md +++ b/readme.md @@ -1,40 +1,89 @@ # Wallpaperctl -- **Note:** Adjust paths as applicable to the desired OS. -- **Note:** The "$" represents the terminal prompt. -- **Note:** Verified to work on Arch Linux with Gnome v3.14 to v42. -## Installation Instructions +A light weight script to automatically set and rotate through computer desktop wallpaper. Desktop wallpaper rotation +is based upon a set duration (default, 1 minute). Wallpaper is randomly selected and defaults to look for wallpaper +from the user's home directory under "Pictures/wallpaper/" (e.g. "/home/adam/Pictures/wallpaper"). -1. Download "wallpaperctl.service", "wallpaperctl.timer" and "gnome_rotate_wallpaper". -2. Move the 3 files to where Systemd user files are stored. -```bash -$ mv wallpaperctl.service wallpaperctl.timer /etc/systemd/user/ +- [Installation](#installation) + - [Assumptions](#assumptions) + - [Dependency Requirements](#dependency-requirements) + - [Setup](#setup) +- [Configuration](#configuration) +- [Custom Settings](#custom-settings) + - [Change Wallpaper Directory](#change-wallpaper-directory) + - [Change Wallpaper Duration](#change-wallpaper-duration) +- [Reference](#reference) + - [Available picture-options](#available-picture-options) +- [External Links](#external-links) + +**Note:** Verified to work on Arch Linux with GNOME v3.14 to v42. + +## Installation + +### Assumptions + +- Have experienced working knowledge within a CLI (command-line interface) +- Understanding of Linux operating system +- Installed all required dependencies as stated in [Dependency Requirements](#dependency-requirements) section +- Installation is done via Linux CLI +- Steps prefixed with a "$" (dollar sign) represents the CLI prompt +- Steps prefixed with a "#" (number sign) represents the CLI prompt with +elevated user permissions (e.g. root) +- The text after the "$" or "#" is to be entered at the CLI +- The installation instructions are an example of installation and configuration + +### Dependency Requirements + +- BASH v5+ +- Git v2+ +- GNOME v3.14+ + +### Setup + +1. Clone the project. +```console +$ git clone https://gitlab.com/adouglas/wallpaperctl.git ``` -3. Move the BASH script "gnome_rotate_wallpaper". -```bash -$ mv gnome_rotate_wallpaper /usr/local/bin/ +1. Change to project directory. +```console +$ cd wallpaperctl ``` -4. Set execute permissions. -```bash -$ chmod +x /usr/local/bin/gnome_rotate_wallpaper +1. Install Systemd unit files. +```console +# cp etc/systemd/user/wallpaperctl.* /etc/systemd/user/ ``` -5. Enable the timer. -```bash +1. Install script file. +```console +# cp usr/local/bin/wallpaperctl /usr/local/bin/ +``` +1. Reload the systemd configuration. +```console +# systemctl daemon-reload +``` +1. Set execute permission. +```console +# chmod +x /usr/local/bin/wallpaperctl +``` + +## Configuration + +1. Enable the Systemd timer. +```console $ systemctl --user enable wallpaperctl.timer ``` -6. Verify the timer is enabled. -```bash +1. Verify the timer is enabled. +```console $ systemctl --user list-unit-files wallpaperctl.service disabled wallpaperctl.timer enabled 2 unit files listed. ``` -7. Start the timer. -```bash +1. Start the Systemd timer. +```console $ systemctl --user start wallpaperctl.timer ``` -8. Verify the timer has been started. -```bash +1. Verify the timer has been started. +```console $ systemctl --user list-timers NEXT LEFT LAST PASSED UNIT ACTIVATES Thu 2016-03-10 18:49:00 CST 1s left Thu 2016-03-10 18:48:56 CST 1s ago wallpaperctl.timer wallpaperctl.service @@ -42,9 +91,11 @@ Thu 2016-03-10 18:49:00 CST 1s left Thu 2016-03-10 18:48:56 CST 1s ago wallpape Pass --all to see loaded but inactive timers, too. ``` -## User Configuration +## Custom Settings -### Change the default wallpaper directory. +### Change Wallpaper Directory + +This alteration will set the location of where wallpapers are stored. 1. Create the required directories. ```bash @@ -57,25 +108,29 @@ $ nano ~/.config/systemd/user/wallpaperctl.conf WALLPAPER_DIR=/home/username/Pictures/wallpaper -### Set the Interval to When the Wallpaper Changes. +### Change Wallpaper Duration -Create the timer file and then change the "OnCalendar" value to the desired interval. Refer to [ArchLinux: systemd/Timers](https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer) for further details. +This alteration will set the duration of how long the wallpaper is displayed for until a new wallpaper is set. 1. Create the required directories. -```bash -$ mkdir ~/.config/systemd ~/.config/systemd/user +```console +$ mkdir -p ~/.config/systemd/user ``` -2. Create the configuration file. -```bash +1. Create the configuration file. +```console $ nano ~/.config/systemd/user/wallpaperctl.timer ``` +1. Change the OnCalendar value as desired. + + Refer to [ArchLinux: systemd/Timers](https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer) for further + details. The below example changes the duration interval from 1 minute to 5 minutes. ``` [Unit] Description=Wallpaperctl - Systemd GNOME wallpaper changer [Timer] -OnCalendar=*:0/1 +OnCalendar=*:0/5 Persistent=true Unit=wallpaperctl.service @@ -83,7 +138,11 @@ Unit=wallpaperctl.service WantedBy=wallpaperctl.service ``` -## Available picture-options +## Reference + +Not applicable at this time. Here for future use. + +### Available picture-options - none - wallpaper