This is the official source tree for the Lumina Desktop Environment.
For additional information about the project, please browse the official website for documentation, screenshots, and more: www.lumina-desktop.org
Lumina Project Info: Table of Contents
- Description
- Latest Versions
- Translations
- How to file bug reports or feature requests
- How to build from source
General Project Information: Table of Contents
The Lumina Desktop Environment is a lightweight system interface that is designed for use on any Unix-like operating system. It takes a plugin-based approach, allowing the entire interface to be assembled/arranged by each individual user as desired, with a system-wide default layout which can be setup by the system administrator. This allows every system (or user session) to be designed to maximize the individual user's productivity.
Supported operating systems include (but are not limited to):
- BSD: TrueOS, FreeBSD, OpenBSD, NetBSD, DragonflyBSD, GNU/kFreeBSD
- Linux: Gentoo, Debian, "Generic" Linux (including Arch, Ubuntu, and more)
Click HERE to see all the available releases for the Lumina Desktop.
Click HERE to see all the available branches of the Lumina Desktop source tree (includes development versions: X.Y.(Z > 0)). The master branch is where all development is performed and tested before the next version is tagged. Additionally, every version (development and release) of the project gets branched off of master at the time the version is tagged, so older versions may be fetched/patched/used as desired.
Occasionally there may be patches committed for particular versions which are not included in the static "release" archives. On the release page these can be identified by a note stating the release is a number of commits behind it's corresponding branch. In this situation, it may be preferable to fetch/use the corresponding branch of the source tree rather than the static archive if the patch(es) which were committed impact your particular operating system.
Legacy Versions (1.0.0 and older)
All the translation files for Lumina are available through the trueos/lumina-i18n reposotiry (Qt5+ only). Please follow the directions in that repository for installing localization files.
Version 1.1.0+
All the translations for Lumina are contained within this repository directly (the i18n/ subdirectories within each project source tree). To include these translation files, the WITH_I18N build flag must be set at compilation time, in which case the translation files will automatically get synced/built alongside the corresponding binaries.
To submit translations, please use the online TrueOS Translation System. Anonymous users may submit translation suggestions, but a website account will be needed to created before you can submit/approve translations directly to the project. See the documentation/information on the site for full details.
Please create a ticket through the GitHub issues tracker on this repository. Similarly, if you want to send in patches or other source contributions, please send in a GitHub pull request so that it can get reviewed/committed as quickly as possible.
- Checkout the source repo to your local box (GitHub gives a few methods for this)
Examples:
- To checkout the master branch of the repo, run
git clone https://github.com/trueos/luminato create a "lumina" directory with a local copy of the source tree. - To update an exising checkout of the Lumina repo, run "git pull" while within your local copy of the source tree.
-
In a terminal, change to the lumina repo directory (base dir, not one of the sub-projects)
-
Run "qmake" on your local system to turn all the Qt project files (*.pro) into Makefiles
- NOTE 1: The Qt5 version of qmake is located in /usr/local/lib/qt5/bin/qmake on FreeBSD, other OS's may have slightly different locations or names for qmake (such as qmake-qt5 for example)
- NOTE 2: Check the terminal output of the qmake command to ensure that your OS build settings were loaded properly. Here is an example:
Project MESSAGE: Build OS Info: FreeBSD, amd64, FreeBSD 10.2-RELEASE-p11 #0: Thu Jan 14 15:48:17 UTC 2016 [email protected]:/usr/obj/usr/src/sys/GENERIC
Project MESSAGE: Build Settings Loaded: FreeBSD
- Build Note: Compile-time options may be set at this time using qmake. This is typically not needed unless you are setting up Lumina for automated build/packaging. If the automatically-detected build settings for your particular OS are invalid or need adjustment, please update the "OS-detect.pri" file as needed and send in your changes so that it can be corrected for future builds.
- PREFIX: Determines the base directory used to install/run Lumina ("/usr/local" by default)
Example:
qmake PREFIX=/usr/local - LIBPREFIX: Determines the location to install the Lumina library ("PREFIX/lib" by default)
Example:
qmake LIBPREFIX=/usr/local/lib - DESTDIR: An optional directory where the compiled files will be placed temporary (such as for packaging/distributing via some other system).
Example:
qmake DESTDIR=/my/build/dir - DEFAULT_SETTINGS: An optional flag to install the default settings/wallpaper for some other operating system (Note: Make sure the OS name is capitalized appropriately!)
Example:
qmake DEFAULT_SETTINGS=TrueOS - WITH_I18N: Generate/install the translation files. (Note: For versions prior to 1.1.0, do not use this flag! The localization files for versions up through 1.0.0 are available in the lumina-i18n repository instead).
Example:
qmake CONFIG+=WITH_I18N - debug: (not recommended for release builds) Do not strip all the debugging information out of the binaries (useful for performing backtraces on builds that crash or for other development tests)
Example:
qmake CONFIG+=debug
-
Run "make" to compile all the Lumina projects (can be done as user)
-
Run "make install" to install the Lumina desktop on your local system (requires admin/root privileges usually)
6-optional) Run "make distclean" to clean up all the build files in the Lumina source tree. (go back to step 3 later)
NOTE: The Lumina project is naturally broken down into a number of individual "sub-projects" which are designed to be built and packaged individually. These sub-projects all use the same overall dependencies, but might have differing library/runtime dependencies or even an alternate minimum-supported version of Qt. The sub-projects are broken down as follows:
- lumina-core: The core of the project (desktop itself)
- lumina-coreutils: The core utilities for configuring/managing the desktop
- desktop-utilities: Various support utilities for desktop systems. Every one of these utilities should be independently packaged.
This section describes where you can find more information about TrueOS and its related projects, file new issues on GitHub, and converse with other users or contributors to the project.
A number of Sphinx generated reStructuredText handbooks are available to introduce you to the TrueOS, Lumina, and SysAdm projects. These handbooks are open source, and users are always encouraged to open GitHub issues or fix any errors they find in the documentation.
The TrueOS User Guide is a comprehensive guide to install TrueOS, along with post-installation configuration help, recommendations for useful utilities and applications, and a help and support section containing solutions for common issues and links to community and development chat channels for uncommon issues. There is also a chapter describing the experimental TrueOS Pico project and links to the Lumina and SysAdm documentation. All TrueOS documentation is hosted on the TrueOS website.
The Lumina Desktop Environment has its own handbook, hosted on the Lumina Website. This handbook contains brief installation instructions. However, due to the highly customizable nature of Lumina, the focus of the handbook lies mainly in documenting all user configurable settings. Each option is typically described in detail, with both text and screenshots. Finally, the suite of unique Qt5 utilities included with Lumina are also documented.
TrueOS users are encouraged to review the Lumina documentation, as the Lumina Desktop Environment is installed by default with TrueOS.
Due to complexity of this project, SysAdm documentation is split into three different guides:
- API Reference Guide (https://api.sysadm.us/getstarted.html)
The Application Programming Interface (API) Reference Guide is a comprehensive library of all API calls and WebSocket requests for SysAdm. In addition to documenting all SysAdm subsystems and classes, the guide provides detailed examples of requests and responses, authentication, and SSL certificate management. This guide is constantly updated, ensuring it provides accurate information at all times.
- Client Handbook (https://sysadm.us/handbook/client/)
The SysAdm Client handbook documents all aspects of the SysAdm client, as well as describing of the PC-BSD system utilities is replaces. Detailed descriptions of utilities such as Appcafe, Life Preserver, and the Boot Environment Manager are contained here, as well as a general guide to using these utilities. TrueOS users are encouraged to reference this guide, as the SysAdm client is included with TrueOS.
- Server Handbook (https://sysadm.us/handbook/server/introduction.html)
The Server handbook is a basic installation guide, walking new users through the process of initializing SysAdm with a bridge and server connection.
Due to the number of repositories under the TrueOS "umbrella", the TrueOS Project consolidates its issue trackers into a few repositories:
- trueos-core : Used for general TrueOS issues, Pico issues, and feature requests.
- lumina : Issues related to using the Lumina Desktop Environment.
- sysadm : Issues with using the SysAdm client or server.
- trueos-docs : Issues related to the TrueOS Handbook.
- lumina-docs : Issues related to the Lumina Handbook.
- sysadm-docs : Issues related to the SysAdm API Guide, Client, and Server Handbooks.
- trueos-website : Issues involving any of the TrueOS Project websites:
The TrueOS handbook has detailed instructions to help you report a bug (https://www.trueos.org/handbook/helpsupport.html#report-a-bug). It is recommended to refer to these instructions when creating new GitHub issues. Better bug reports usually result in faster fixes!
To request a feature, open a new issue in one of the related GitHub issue repositories and begin the title with Feature Request:.
The TrueOS community has a wide variety of chat channels and forum options available for users to interact with not only each other, but contributors to the project and the core development team too.
TrueOS has a Discourse channel managed concurrently with the TrueOS Subreddit. New users need to sign up with Discourse in order to create posts, but it is possible to view posts without an account.
The TrueOS Project uses Gitter to provide real-time chat and collaboration with TrueOS users and developers. Gitter does not require an application to use, but does require a login using either an existing GitHub or Twitter account.
To access the TrueOS Gitter community, point a web browser to https://gitter.im/trueos.
Gitter also maintains a full archive of the chat history. This means lengthy conversations about hardware issues or workarounds are always available for reference. To access the Gitter archive, navigate to the desired TrueOS room’s archive. For example, here is the address of the TrueOS Lobby archive: https://gitter.im/trueos/Lobby/archives.
Like many open source projects, TrueOS has an Internet Relay Chat (IRC) channel so users can chat and get help in real time. To get connected, use this information in your IRC client:
- Server name: irc.freenode.net
- Channel name: #trueos (note the # is required)
The TrueOS Project also has a Subreddit for users who prefer to use Reddit to ask questions and to search for or post how-tos. A Reddit account is not required in order to read the Subreddit, but it is necessary to create a login account to submit or comment on posts.
The TrueOS Project also maintains a number of social media accounts you can watch:
- Facebook: https://www.facebook.com/groups/4210443834/
- Linkedin: http://www.linkedin.com/groups?gid=1942544
- TrueOS Blog: https://www.trueos.org/blog/
- Twitter: https://twitter.com/TrueOS_Project/