diff --git a/README.md b/README.md index 12de1d7..e3c2a0f 100644 --- a/README.md +++ b/README.md @@ -3,101 +3,69 @@ # AtomicXR # -XR for Universal Blue and Fedora Atomic Desktops. +AtomicXR is no longer maintained. The following tools replace it, and achieve the same goals much more practical way: +- VR Homebrew Tap -> [Homebrew-XR](https://tangled.org/matrixfurry.com/homebrew-xr) +- Envision on Fedora Atomic -> [Envision-OCI](https://tangled.org/matrixfurry.com/envision-oci) +- VR system configuration -> [LXRAC](https://tangled.org/matrixfurry.com/lxrac) -This repo contains the AtomicXR core libraries and CLI. Other AtomicXR repos can be found below: +# Migration Guide # -- [AtomicXR Homebrew Tap](https://tangled.org/@matrixfurry.com/homebrew-atomicxr): XR packaging for Fedora Atomic. +As of March 27, 2026, the AtomicXR CLI and Homebrew Tap have received their last updates, and have been replaced with +better solutions. The changes are outlined below, with a script to help you migrate more easily. -AtomicXR is developed and tested on Fedora, but should work with: +## Auto-migration script ## -- [Bluefin](https://projectbluefin.io/) -- [Bazzite](https://bazzite.gg/) -- [Fedora Silverblue](https://fedoraproject.org/atomic-desktops/silverblue/) -- Other Fedora Atomic-based distros +This script will walk you through the migration process: +`bash -c "$(curl -fsSL https://tangled.org/matrixfurry.com/atomic-xr/raw/main/migrate.sh)"` -> See also: [LVRA Wiki page](https://lvra.gitlab.io/docs/distros/fedora_atomic/) for Fedora Atomic +If you'd like to learn more about the changes and why they were made, please read the next section. -## Install ## +## Changes ## -Homebrew (recommended): -`brew tap matrixfurry.com/atomicxr https://tangled.org/matrixfurry.com/homebrew-atomicxr; brew install atomicxr-cli` +The script will walk you through what has changed, but if you want to learn more about *why* things have changed, this +is the section for you. -From this repo: `./install.sh` +### 1. The AtomicXR Homebrew Tap has been replaced by Homebrew-XR -## Usage ## +AtomicXR Homebrew Tap contained software that was specifically intended to only work on Fedora Atomic Desktops and +Universal Blue distros (e.g. Bazzite). The builds there were often out of date, missing features that people needed, or +just didn't work at all. -> [!IMPORTANT] -> To build profiles in Envision, right click it in your desktop's menu and select "Launch in Build Mode" +Homebrew-XR contains even more VR software, stays up to date, and works on almost any distro +where Homebrew is installed, including Bazzite and Fedora. -For an easy-to-follow guide, please see the [LVRA Wiki page](https://lvra.gitlab.io/docs/distros/fedora_atomic/) for Fedora Atomic. +### 2. Envision in Distrobox (`axr envision`) has been replaced with Envision-OCI -Common CLI functions: +The old process for getting Envision to build software inside a container was complex, hard to understand, and very +prone to breaking. -- List available CLI functions: `axr -l` -- Install Envision: `axr envision install` -- Update Envision: `axr envision upgrade` -- Set up Steam Flatpak XR: `axr flatpak steam enable-xr` -- Launch [OSC Avatar Manager](https://github.com/galister/oscavmgr): `axr oscavmgr start [babble|openxr|alvr]` (use - `openxr` for WiVRn) +When Envision was installed or updated via the AtomicXR CLI, it would: +1. Create a Fedora Distrobox container, then manually install all the build dependencies for Envision, Monado, WiVRn, WMR, etc. +2. Delete any previously installed build of Envision and start from scratch +3. Download the Envision source code and apply patches for the homebrew plugin system +4. Create an entirely separate "build mode" that runs envision itself in the Distrobox container +5. Build Envision from source -If you plan to use the SteamVR Lighthouse driver with Flatpak Steam or WiVRn (without a lighthouse-tracked headset), you -can calibrate using AtomicXR instead of Envision: `axr steamvr-lh calibrate` +That approach caused countless bugs and hard-to-understand issues for people. Runtime libraries would be missing on the +host, Envision sometimes wouldn't launch outside of build mode, builds would randomly fail, Monado couldn't run inside +of build mode, etc. -You may have to launch Envision in build mode to install WiVRn on your headset via ADB +Maintenance was also very tedious and difficult. Anytime something was updated or fixed, more bugs +would appear. Eventually, it got too out of date, and no longer could install or run at all. -## Troubleshooting ## +Luckily, you don't have to worry about any of that anymore. Envision-OCI takes a much simpler approach, it just uses a +shim to run builds in Podman, from pre-built container images that include all the required build dependencies out of +the box. All it needs to work is a modified PATH containing the shims, no more manual patches or building from source required. -### Missing dependencies while building Envision profiles +Pre-built Monado packages will also be available soon in the Homebrew-XR repository. Most people won't need to worry about +building it themselves. You'll be able to install Monado in seconds, and use Envision as an easy launcher and configuration tool. -Make sure you're launching Envision in build mode; right click Envision in your application menu and select "Launch in -Build Mode". +### 3. AtomicXR CLI's manual system configuration commands have been replaced by [LXRAC](https://tangled.org/matrixfurry.com/lxrac) -If you still get missing dependency errors while in build mode, try resetting the Envision build container: -`axr envision uninstall && axr envision install` +Using the AtomicXR CLI to manually configure your system was confusing and not at all obvious. Most people using AtomicXR +never touched anything but `axr envision install`, and there was no real way to know which commands you needed to run to +properly configure your system. If anything, these features caused more confusion than solved issues. -If you get errors after resetting the container and launching in build mode, -please [open an issue](https://tangled.sh/@matrixfurry.com/atomic-xr/issues/new): - -- Prefix the title with "[Envision/build]" -- Attach your Envision profile to the report - - Click the menu button next to the profile name in Envision - - Select "Export Profile" - -### Formulae found in multiple taps - -If you had AtomicXR or the Homebrew tap installed before Aug 10, 2025, you might see an error message like: - -``` -Error: Formulae found in multiple taps: - * shiloh/atomicxr/atomicxr-cli - * matrixfurry.com/atomicxr/atomicxr-cli -``` - -To resolve this, remove the old tap with `brew untap shiloh/atomicxr` - -### `unknown flag: -o` for `reject` function - -- Make sure your Nushell version (`nu -v`) is up to date, `0.106.0` is the minimum required version. - -### ADB reports that there are no devices connected - -Add yourself to the `plugdev` group with `sudo usermod -a -G plugdev $USER`, then reboot - -### Failed to connect to system bus: Could not connect: No such file or directory - -This is caused by the system DBus not being available in Distrobox. Try launching Envision normally (not in build mode). - -### Envision Plugin download failed - -Plugins should be installed from the AtomicXR Homebrew Tap instead of Envision. Envision doesn't provide a way to -download plugins via a command (yet). - -See the [AtomicXR Homebrew Tap](https://tangled.sh/@matrixfurry.com/homebrew-atomicxr) for a list of plugins you can -install. - -## Support ## - -You can open an issue on [Tangled](https://tangled.sh/@matrixfurry.com/atomic-xr/issues), ask questions -in [this post](https://discord.com/channels/1065291958328758352/1389409336580767775) on the LVRA Discord, -or [contact me](https://woosh.link/matrixfurry.com) directly. +[lxrac](https://tangled.org/matrixfurry.com/lxrac) (Linux XR Auto-Configuration) provides an easy way to automatically +configure your system optimally for VR. It will detect what VR software you're running and automatically apply the best +configuration for you, no manual work needed. diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md deleted file mode 100644 index a90b5a3..0000000 --- a/docs/code_of_conduct.md +++ /dev/null @@ -1,90 +0,0 @@ -# Contributor Covenant 3.0 Code of Conduct - -## Our Pledge - -We pledge to make our community welcoming, safe, and equitable for all. - -We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant. - -## Encouraged Behaviors - -While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language. - -With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including: - -1. Respecting the **purpose of our community**, our activities, and our ways of gathering. -2. Engaging **kindly and honestly** with others. -3. Respecting **different viewpoints** and experiences. -4. **Taking responsibility** for our actions and contributions. -5. Gracefully giving and accepting **constructive feedback**. -6. Committing to **repairing harm** when it occurs. -7. Behaving in other ways that promote and sustain the **well-being of our community**. - - -## Restricted Behaviors - -We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct. - -1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop. -2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people. -3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits. -4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community. -5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission. -6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group. -7. Behaving in other ways that **threaten the well-being** of our community. - -### Other Restrictions - -1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions. -2. **Failing to credit sources.** Not properly crediting the sources of content you contribute. -3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community. -4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors. - - -## Reporting an Issue - -Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. - -When an incident does occur, it is important to report it promptly. To report a possible violation, **Please send a message via [SimpleX](https://smp18.simplex.im/a#Wc2x2IBqqwzgmeGkN0XtKrGMLBxFuxmoYgkTGgGgR0M), [Email](mailto:matrix@matrixfurry.com), or any of the contact methods listed [here](https://woosh.link/matrixfurry.com).** - -Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. - - -## Addressing and Repairing Harm - -**** - -If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped. - -1) Warning - 1) Event: A violation involving a single incident or series of incidents. - 2) Consequence: A private, written warning from the Community Moderators. - 3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations. -2) Temporarily Limited Activities - 1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation. - 2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members. - 3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over. -3) Temporary Suspension - 1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation. - 2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions. - 3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted. -4) Permanent Ban - 1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member. - 2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior. - 3) Repair: There is no possible repair in cases of this severity. - -This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community. - - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. - - -## Attribution - -This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). - -Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/) - -For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion). diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index d1d258c..0000000 --- a/docs/contributing.md +++ /dev/null @@ -1,77 +0,0 @@ -For the most up-to-date guide, please see [matrixfurry.com/common](https://tangled.org/@matrixfurry.com/common/blob/main/CONTRIBUTING.md). - -Development happens on [Tangled](https://tangled.org/did:plc:zmjoeu3stwcn44647rhxa44o). - -# Developer Certificate of Origin -By submitting code contributions as an individual or on behalf of a corporation to any directory in this repository, you agree to the [Developer Certificate of Origin](./legal/DCO.txt) - -# Reporting issues -Yes, issues are contributions. - -First, look around in the opened and closed issues, someone might have reported the same issue. - -If you're not sure an issue is the same or not, especially an older closed issue, open a new issue and mention that you suspect it could be related. - -# Commit guidelines - -We follow a similar commit style to Tangled. Please keep your commits: -- **atomic**: each commit should represent one logical change -- **descriptive**: the commit message should clearly describe what the change does and why it's needed - -## Message format -We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines for commit messages. At present, it's not strictly enforced, but is preferred. - -Notes: -- Keep commits lowercased with no trailing period, following the Conventional Commits style. -- Use the imperative mood in the summary line (e.g., "fix bug" not "fixed bug" or "fixes bug"). -- Try to keep the summary line under 72 characters. -- Follow the same formatting for PR titles if filled manually. -- Don't include unrelated changes in the same commit (keep commits atomic). -- Avoid noisy commit messages like "wip" or "final fix". - -## Commit signing - -Commit signing is optional but highly recommended. Once you make your first signed commit, all future commits must be signed. - -Please see the [security policy](./security.md) for more information. - -## Submitting changes - -Opening a Pull Request on Tangled is the preferred contribution workflow. - -We reccomend using [Jujutsu](https://github.com/jj-vcs/jj) if you're comfortable with it. This way you can take advantage of Tangled's [stacked PRs](https://blog.tangled.org/stacking). - -PRs get merged "as-is" (fast-forward) -- like applying a patch-series using `git am`. At present, there is no squashing -- so please author your commits as they would appear on `main`, following the above guidelines. Rewrite history before submitting if necessary. - -# "AI"-assisted contributions -> NOTE: Using pre-existing boilerplate, snippets, or syntax suggestions from your IDE or standard Language Server are not considered AI-assisted changes. You're welcome to use those features. - -Contributions written largely with help of LLMs (Large Language Models), Generative AI, or similar systems are not welcome. - -These systems are generally using statistical models built on content acquired without the author's consent, and with disregard of the content's license and attribution. They also consume a huge amount of energy, and have a very large impact on the environment. - -This includes, but is not limited to: -- Comments -- Documentation -- Code -- Issues -- Images, Videos, Audio, or other Assets - -Contributions should be largely authored by the people in the commit information, e.g. the `Committer`, `Author`, `Signed-off-by`, and `Co-authored-by` fields. - -If you are unsure, or you had help from automated AI-generation in part of your contribution, please tell us when contributing. It does not mean the contribution will be rejected outright. We will evaluate on a case-by-case basis. We value honesty, and take it into consideration. - -# Security -Please see the [security policy](./security.md) - -# Maintainers - -## Releases -We use [Semantic Versioning](https://semver.org/) for our version numbers. - -Given a version number `MAJOR.MINOR.PATCH`, increment the: -- `MAJOR` version when you make incompatible API changes -- `MINOR` version when you add functionality in a backward compatible manner -- `PATCH` version when you make backward compatible bug fixes - -Additional labels for pre-release and build metadata are available as extensions to the `MAJOR.MINOR.PATCH` format. diff --git a/docs/legal/DCO.txt b/docs/legal/DCO.txt deleted file mode 100644 index 49b8cb0..0000000 --- a/docs/legal/DCO.txt +++ /dev/null @@ -1,34 +0,0 @@ -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. diff --git a/docs/security.md b/docs/security.md deleted file mode 100644 index 6b59ad9..0000000 --- a/docs/security.md +++ /dev/null @@ -1,67 +0,0 @@ -For the most up-to-date security policy, please see [matrixfurry.com/common](https://tangled.org/@matrixfurry.com/common/blob/main/docs/security.md). - -# Reporting -Please report security issues via [SimpleX](https://smp18.simplex.im/a#Wc2x2IBqqwzgmeGkN0XtKrGMLBxFuxmoYgkTGgGgR0M) or [Email](mailto:shiloh@shilohfen.com). - -> If you want to send an encrypted email, my public key fingerprint is [DD7EB0BAA822169398828C45103DD5193B6A77CB](https://keys.openpgp.org/vks/v1/by-fingerprint/DD7EB0BAA822169398828C45103DD5193B6A77CB). - -Please do not report security issues on the project's issue tracker. - -# Commit signing - -Commit signing is optional but highly recommended. Once you make your first signed commit, all future commits must be signed. - -SSH signing is preferred over PGP signing. - -To enable signature verification, add your public key to your Tangled profile, and optionally the `.allowed_signers` file in the project's repo. - -Tangled profiles should be trusted over the repo's copy, excluding revoked keys. - -## Setup -Replace `` with the SSH key or keyfile you'd like to use (eg. `~/.ssh/id_ed25519`). - -Git: -```sh -git config --global gpg.format ssh -git config --global user.signingkey -git config --global commit.gpgsign true -``` - -Jujutsu: -```sh -jj config set --user signing.behavior own -jj config set --user signing.backend ssh -jj config set --user signing.key -``` - -Add the public key to your Tangled profile at https://tangled.org/settings/keys - -Optionally, add your public key to the repo's `.allowed_signers` file: -- Git: `echo "$(git config user.email) $(cat ~/.ssh/id_ed25519.pub)" >> .allowed_signers` -- Jujutsu: `echo "$(jj config get user.email) $(cat ~/.ssh/id_ed25519.pub)" >> .allowed_signers` - -## Key Revocation -Revoked keys are listed in `.revoked_keys` ([OpenSSH KRL](https://man.openbsd.org/ssh-keygen.1#KEY_REVOCATION_LISTS) format). Keys must never be reinstated or removed from this file. After a revocation, you must create a new key to continue contributing to the project. - -A key revocation must be signed by either: -1. The key being revoked - - Anyone with access to the private key can create the revocation commit - -2. A maintainer with proof of compromise - - The maintainer must have significant evidence that the key has been compromised - - The maintainer must attempt to reach out to the contributor to confirm - - The commit message must provide details of why the key is being revoked - -### Instructions - -Add the key to the `.revoked_keys` file: -```sh -ssh-keygen -k -u -f .revoked_keys -``` - -View the revoked keys: -```sh -ssh-keygen -Q -l -f .revoked_keys -``` - -For more information, see the [ssh-keygen(1) manpage](https://man.openbsd.org/ssh-keygen.1#k) diff --git a/migrate.nu b/migrate.nu new file mode 100644 index 0000000..736701c --- /dev/null +++ b/migrate.nu @@ -0,0 +1,4 @@ +#!/usr/bin/env nu +# SPDX-License-Identifier: AGPL-3.0-only +# Copyright (c) 2026 MatrixFurry + diff --git a/migrate.sh b/migrate.sh new file mode 100644 index 0000000..f492944 --- /dev/null +++ b/migrate.sh @@ -0,0 +1,4 @@ +#!/usr/bin/bash +# SPDX-License-Identifier: AGPL-3.0-only +# Copyright (c) 2026 MatrixFurry +