├── _static ├── .keepme ├── dark_mode.js └── dark_mode.css ├── _templates └── .keepme ├── .gitignore ├── requirements.txt ├── user ├── upgrade-img │ ├── completed.png │ ├── progress.png │ ├── notification.png │ └── upgrade_window.png ├── installation-guide │ ├── images │ │ ├── custom-installation │ │ │ ├── 3-select-gpt.png │ │ │ ├── 5-efi-partition.png │ │ │ ├── 6-zfs-partition.png │ │ │ ├── 7-swap-partition.png │ │ │ ├── 2-no-partition-table.png │ │ │ ├── 1-custom-partitioning.png │ │ │ ├── 4-with-partition-table.png │ │ │ └── 8-completed-partitioning.png │ │ └── full-disk-installation │ │ │ ├── 1-desktop.png │ │ │ ├── 0-boot-bios.png │ │ │ ├── 0-boot-uefi.png │ │ │ ├── 10-progress.png │ │ │ ├── 11-complete.png │ │ │ ├── 5-install-type.png │ │ │ ├── 7-loader-uefi.png │ │ │ ├── 8-accounts-root.png │ │ │ ├── 9-accounts-user.png │ │ │ ├── 6-install-location.png │ │ │ ├── 2-localization-language.png │ │ │ ├── 3-localization-keyboard.png │ │ │ └── 4-localization-timezone.png │ ├── installation-guide.md │ ├── installation-guide-pl.md │ ├── troubleshooting-pl.md │ ├── troubleshooting.md │ ├── full-disk-installation.md │ ├── full-disk-installation-pl.md │ ├── custom-installation.md │ ├── custom-installation-pl.md │ ├── getting-started.md │ └── getting-started-pl.md ├── upgrading-guide.md ├── FAQ.md └── security-key.md ├── contributor ├── community │ ├── index.md │ ├── users-support.md │ └── users-support-pl.md ├── documentation │ ├── index.md │ ├── getting-started-pl.md │ └── getting-started.md ├── translations │ ├── index.md │ └── translate-python.md ├── index.md ├── maintenance-release │ ├── index.md │ ├── versioning-guide.md │ ├── maintaining-ports-tree.md │ ├── package-process.md │ └── maintaining-src-tree.md ├── code │ ├── index.md │ ├── development-setup.md │ └── python-guide.md └── getting-started │ ├── index.md │ ├── contributor-levels.md │ ├── contributor-levels-pl.md │ ├── ghostbsd-contributors-guide.md │ └── ghostbsd-contributors-guide-pl.md ├── .github ├── CODEOWNERS ├── FUNDING.yml └── workflows │ └── project_automation.yml ├── Makefile ├── make.bat ├── legal ├── trademark.md └── license.md ├── .readthedocs.yaml ├── README.md ├── index.md ├── index-pl.md └── conf.py /_static/.keepme: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /_templates/.keepme: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build/* 2 | 3 | # Editor directories and files 4 | .vscode/ 5 | .idea/ 6 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | linkify-it-py 2 | myst-parser 3 | sphinx-autobuild 4 | sphinx-rtd-theme -------------------------------------------------------------------------------- /user/upgrade-img/completed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/upgrade-img/completed.png -------------------------------------------------------------------------------- /user/upgrade-img/progress.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/upgrade-img/progress.png -------------------------------------------------------------------------------- /user/upgrade-img/notification.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/upgrade-img/notification.png -------------------------------------------------------------------------------- /user/upgrade-img/upgrade_window.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/upgrade-img/upgrade_window.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/3-select-gpt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/3-select-gpt.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/1-desktop.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/1-desktop.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/5-efi-partition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/5-efi-partition.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/6-zfs-partition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/6-zfs-partition.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/0-boot-bios.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/0-boot-bios.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/0-boot-uefi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/0-boot-uefi.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/10-progress.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/10-progress.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/11-complete.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/11-complete.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/7-swap-partition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/7-swap-partition.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/5-install-type.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/5-install-type.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/7-loader-uefi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/7-loader-uefi.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/2-no-partition-table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/2-no-partition-table.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/8-accounts-root.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/8-accounts-root.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/9-accounts-user.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/9-accounts-user.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/1-custom-partitioning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/1-custom-partitioning.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/4-with-partition-table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/4-with-partition-table.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/6-install-location.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/6-install-location.png -------------------------------------------------------------------------------- /user/installation-guide/images/custom-installation/8-completed-partitioning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/custom-installation/8-completed-partitioning.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/2-localization-language.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/2-localization-language.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/3-localization-keyboard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/3-localization-keyboard.png -------------------------------------------------------------------------------- /user/installation-guide/images/full-disk-installation/4-localization-timezone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ghostbsd/documentation/HEAD/user/installation-guide/images/full-disk-installation/4-localization-timezone.png -------------------------------------------------------------------------------- /contributor/community/index.md: -------------------------------------------------------------------------------- 1 | # Community Involvement 2 | 3 | Get involved in the GhostBSD community! Whether you're providing user support, participating in development discussions, or helping newcomers, community involvement is a valuable way to contribute to GhostBSD. 4 | 5 | - [Users Support](users-support.md) - Help other GhostBSD users by answering questions and providing support -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Each line is a file pattern followed by one or more owners. 2 | 3 | # These owners will be the default owners for everything in 4 | # the repo. Unless a later match takes precedence, 5 | # @global-owner1 and @global-owner2 will be requested for 6 | # review when someone opens a pull request. 7 | # * @global-owner1 @global-owner2 8 | * @ghostbsd/contributors @ghostbsd/new-contributors @ghostbsd/core-contributors @ghostbsd/project-leader 9 | -------------------------------------------------------------------------------- /contributor/documentation/index.md: -------------------------------------------------------------------------------- 1 | # Contributing Documentation 2 | 3 | Welcome to the GhostBSD documentation contribution guide! Help us improve and expand our documentation to make GhostBSD more accessible to users and contributors. 4 | 5 | - [Getting Started with Documentation](getting-started.md) - Learn how to contribute to GhostBSD documentation 6 | 7 | This section covers the complete process of writing, editing, and maintaining GhostBSD documentation, from initial setup through publication. -------------------------------------------------------------------------------- /user/installation-guide/installation-guide.md: -------------------------------------------------------------------------------- 1 | Installation Guide 2 | ================== 3 | 4 |

Introduction

5 | 6 | GhostBSD comes with a Graphical installer called GBI. 7 | 8 | After reading this guide, you will know: 9 | 10 | * How to make a USB memory stick. 11 | * How to set up a Virtual Machine. 12 | * How to install GhostBSD. 13 | * How to install GhostBSD using the entire disk drive. 14 | * How to install alongside other operating system(s). 15 | * Troubleshooting the installer and live media. 16 | 17 | ```{toctree} 18 | :caption: Table of Contents 19 | 20 | getting-started 21 | full-disk-installation 22 | custom-installation 23 | troubleshooting 24 | ``` 25 | -------------------------------------------------------------------------------- /user/installation-guide/installation-guide-pl.md: -------------------------------------------------------------------------------- 1 | Przewodnik instalacji 2 | ===================== 3 | 4 |

Wprowadzenie

5 | 6 | GhostBSD zawiera graficzny instalator o nazwie GBI. 7 | 8 | Po przeczytaniu tego przewodnika będziesz wiedział: 9 | 10 | * Jak przygotować pamięć USB. 11 | * Jak skonfigurować maszynę wirtualną. 12 | * Jak zainstalować GhostBSD. 13 | * Jak zainstalować GhostBSD na całym dysku twardym. 14 | * Jak zainstalować obok innego systemu operacyjnego. 15 | * Rozwiązywanie problemów z instalatorem i nośnikami live. 16 | 17 | ```{toctree} 18 | :caption: Spis treści 19 | 20 | getting-started 21 | full-disk-installation 22 | custom-installation 23 | troubleshooting 24 | ``` -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] 4 | patreon: GhostBSD 5 | open_collective: # Replace with a single Open Collective username 6 | ko_fi: # Replace with a single Ko-fi username 7 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel 8 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry 9 | liberapay: # Replace with a single Liberapay username 10 | issuehunt: # Replace with a single IssueHunt username 11 | otechie: # Replace with a single Otechie username 12 | custom: ['https://www.ghostbsd.org/donate'] # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] 13 | -------------------------------------------------------------------------------- /contributor/translations/index.md: -------------------------------------------------------------------------------- 1 | # Translation Contribution 2 | 3 | Help make GhostBSD accessible to users worldwide by contributing translations for our Python tools and applications. 4 | 5 | ## What Can Be Translated 6 | 7 | GhostBSD has several Python-based tools that need translation: 8 | - NetworkMgr, Update Station, Install Station, Setup Station 9 | - Station Tweak, Software Station, Backup Station, GBI Installer 10 | 11 | ## Translation Guides 12 | 13 | - [Python Tool Translation](translate-python.md) - Complete workflow for translating GhostBSD Python applications 14 | 15 | ## Getting Started 16 | 17 | All GhostBSD Python tools use standard gettext workflows with management commands in `setup.py`. See the detailed guide above for step-by-step instructions. 18 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /contributor/index.md: -------------------------------------------------------------------------------- 1 | # Contributor Documentation 2 | 3 | Welcome to the GhostBSD contributor documentation! This section is for developers, testers, documentation writers, translators, and anyone else interested in helping improve GhostBSD. 4 | 5 | ## How to Contribute 6 | 7 | - [Getting Started](getting-started/index) – Learn how to make your first contribution to GhostBSD. 8 | - [Contributing Code](code/index) – Guidelines for contributing code, including Python and C development. 9 | - [Maintenance And Release](maintenance-release/index) – Help maintain ports, src, packages, releases, and versioning. 10 | - [Contributing Documentation](documentation/index) – Write or improve our documentation, including user and contributor guides. 11 | - [Contributing Translations](translations/index) – Help translate GhostBSD into additional languages. 12 | - [Community Involvement](community/index) – Get involved in our community, including user support and development discussions. -------------------------------------------------------------------------------- /legal/trademark.md: -------------------------------------------------------------------------------- 1 | Trademarks 2 | ========== 3 | 4 | This is a list of trademarks for projects used by or mentioned by GhostBSD. 5 | 6 | - FreeBSD® is a registered trademark of The FreeBSD Foundation. 7 | 8 | - GNOME® and GTK® are registered trademarks of The GNOME Foundation. 9 | 10 | - Intel™ is a trademark of Intel Corporation or its subsidiaries. 11 | 12 | - Oracle®, Solaris®, OpenSolaris®, VirtualBox®, and ZFS® are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. 13 | 14 | - UNIX® is a registered trademark of The Open Group. -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # Read the Docs configuration file for Sphinx projects 2 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 3 | 4 | # Required 5 | version: 2 6 | # Set the OS, Python version and other tools you might need 7 | build: 8 | os: ubuntu-22.04 9 | tools: 10 | python: "3.9" 11 | 12 | # Build documentation in the "docs/" directory with Sphinx 13 | sphinx: 14 | configuration: conf.py 15 | 16 | # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs 17 | # builder: "dirhtml" 18 | # Fail on all warnings to avoid broken references 19 | # fail_on_warning: true 20 | 21 | # Optionally build your docs in additional formats such as PDF and ePub 22 | # formats: 23 | # - pdf 24 | # - epub 25 | 26 | # Optional but recommended, declare the Python requirements required 27 | # to build your documentation 28 | # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html 29 | python: 30 | install: 31 | - requirements: requirements.txt -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | GhostBSD documentation portal 2 | ============================= 3 | This repository is replacing https://wiki.ghostbsd.org/. 4 | 5 | Each change committed here triggers an automated build that results in an update to the portal: 6 | 7 | * https://ghostbsd-documentation-portal.readthedocs.io/ 8 | 9 | Automation involves Sphinx, myst-parser, Markdown, and a hook with the portal. 10 | 11 | ## Local development server 12 | 13 | Use a local development server that regenerates the output whenever the input changes: 14 | 15 | ``` 16 | git clone git@github.com:ghostbsd/documentation.git 17 | sudo pkg install -y py311-pip 18 | sudo pip install sphinx sphinx-rtd-theme myst-parser sphinx-autobuild 19 | cd documentation 20 | sphinx-autobuild . build/html 21 | ``` 22 | 23 | Then, open http://127.0.0.1:8000/index.html in a web browser. It will be regenerated and refreshed whenever a changed file is saved. 24 | 25 | ## Generating documentation 26 | 27 | One can also generate documentation, in various output formats, locally: 28 | 29 | ``` 30 | gmake html 31 | gmake epub 32 | ``` 33 | -------------------------------------------------------------------------------- /contributor/maintenance-release/index.md: -------------------------------------------------------------------------------- 1 | # Maintenance And Release Contribution 2 | 3 | Welcome to the GhostBSD maintenance and release contribution documentation! This section covers the overall maintenance of GhostBSD including ports, packages, OS source code (src), release process, versioning, and other related topics. 4 | 5 | ## Ports and Packages 6 | 7 | - [Package Management Process](package-process.md) - Understanding GhostBSD's three-tier package repository system 8 | - [Maintaining GhostBSD Ports in Sync with FreeBSD Ports](maintaining-ports-tree.md) - Learn how to keep our ports current with FreeBSD 9 | 10 | ## Source Code Maintenance 11 | 12 | - [Maintaining GhostBSD Src in Sync with FreeBSD Src](maintaining-src-tree.md) - Learn how to keep our src tree current with FreeBSD and manage stable/releng branches 13 | 14 | ## Release Process 15 | 16 | - [GhostBSD Versioning Guide](versioning-guide.md) - Understanding GhostBSD's versioning scheme and release numbering 17 | 18 | This section covers the complete process of creating and managing GhostBSD releases, from source code updates through final distribution. -------------------------------------------------------------------------------- /user/installation-guide/troubleshooting-pl.md: -------------------------------------------------------------------------------- 1 | Rozwiązywanie problemów 2 | ======================== 3 | 4 | ## System live nie uruchamia się. 5 | 6 | ### Twoje urządzenie może nie być obsługiwane. 7 | 8 | GhostBSD opiera się na stabilnej gałęzi FreeBSD i obsługa sprzętu może się często zmieniać. Obsługa sprzętu jest zazwyczaj dobra, jednak niektóre nowsze urządzenia mogą mieć problemy. Możesz spróbować uruchomić system live na innym komputerze, aby określić, czy problem dotyczy sprzętu, czy samego bootowalnego USB. 9 | 10 | Proszę zapoznać się z [Kompatybilnością sprzętową FreeBSD](https://docs.freebsd.org/en/books/faq/#hardware) w celu uzyskania informacji o poszczególnych komponentach. 11 | 12 | ### Nośnik instalacyjny może być uszkodzony. 13 | 14 | Czasami pliki ISO mogą zostać uszkodzone podczas pobierania lub tworzenia bootowalnego pendrive'a USB. Proszę zapoznać się z przewodnikiem [Jak zacząć](getting-started.md), aby pobrać nowy plik ISO i stworzyć nowy bootowalny pendrive USB. 15 | 16 | ## System live nie dociera do środowiska graficznego. 17 | 18 | ### ISO instalacyjne mogą być przestarzałe lub wymagać ogólnych poprawek. 19 | 20 | Spróbuj stworzyć bootowalny USB za pomocą [najnowszego ISO](https://www.ghostbsd.org/download) dostępnego na stronie Pobierania w sekcji *Najnowsze wersje*. GhostBSD jest wersją rolling release i czasami aktualizacje i poprawki są wdrażane do najnowszej wersji przed utworzeniem nowego oficjalnego obrazu. 21 | 22 | *Proszę zauważyć*: Ta sekcja jest niekompletna i obecnie jest aktualizowana. -------------------------------------------------------------------------------- /legal/license.md: -------------------------------------------------------------------------------- 1 | Copyrights and licenses 2 | ======================= 3 | 4 | This is a list of copyrights and licenses for GhostBSD or projects used by GhostBSD. 5 | 6 | - [GhostBSD Copyright](https://www.ghostbsd.org/about/license) 7 | 8 | - Berkeley Software Distribution License (BSD) 9 | - FreeBSD Copyright 10 | - FreeBSD Documentation License 11 | - 4.4BSD Copyright 12 | 13 | - Creative Commons Attribution-ShareAlike license (CC BY-SA 3.0) 14 | 15 | - GNU General Public License (GPL) 16 | - Version 2 17 | - Version 3 18 | 19 | - GNU Lesser (Library) General Public License (LGPL) 20 | - Version 2 21 | - Version 3 22 | 23 | - Additional information about open-source licenses 24 | - Open Source Initiative 25 | - Wikipedia comparison page 26 | -------------------------------------------------------------------------------- /_static/dark_mode.js: -------------------------------------------------------------------------------- 1 | document.addEventListener('DOMContentLoaded', function () { 2 | const breadcrumbs = document.querySelector('.wy-breadcrumbs'); 3 | if (!breadcrumbs) { 4 | console.error('Breadcrumbs element (.wy-breadcrumbs) not found!'); 5 | return; 6 | } 7 | 8 | const toggleButton = document.createElement('button'); 9 | toggleButton.style.marginLeft = '20px'; 10 | 11 | function updateButtonText() { 12 | toggleButton.textContent = document.body.classList.contains('dark-mode') ? 'Light Mode' : 'Dark Mode'; 13 | } 14 | 15 | breadcrumbs.appendChild(toggleButton); 16 | 17 | const prefersDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches; 18 | const savedPreference = localStorage.getItem('darkMode'); 19 | 20 | if (savedPreference !== null) { 21 | if (savedPreference === 'true') { 22 | document.body.classList.add('dark-mode'); 23 | } else { 24 | document.body.classList.remove('dark-mode'); 25 | } 26 | } else if (prefersDarkMode) { 27 | document.body.classList.add('dark-mode'); 28 | } 29 | 30 | updateButtonText(); 31 | 32 | toggleButton.addEventListener('click', function () { 33 | document.body.classList.toggle('dark-mode'); 34 | localStorage.setItem('darkMode', document.body.classList.contains('dark-mode')); 35 | updateButtonText(); 36 | }); 37 | 38 | window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => { 39 | if (localStorage.getItem('darkMode') === null) { 40 | document.body.classList.toggle('dark-mode', e.matches); 41 | updateButtonText(); 42 | } 43 | }); 44 | }); -------------------------------------------------------------------------------- /contributor/code/index.md: -------------------------------------------------------------------------------- 1 | # Contributing Code 2 | 3 | Welcome to code contribution for GhostBSD! Whether you're interested in Python applications, C system tools, or shell scripts, this section will help you get set up and contributing. 4 | 5 | ## What We Build 6 | 7 | GhostBSD development spans several areas: 8 | 9 | ### User Applications (Python + GTK3) 10 | Our desktop tools are built with Python and GTK3: 11 | - **NetworkMgr** - Network connection management 12 | - **Update Station** - System update interface 13 | - **Software Station** - Package management GUI 14 | - **System tools** - Various configuration utilities 15 | 16 | ### System Components (C) 17 | Lower-level system integration with FreeBSD base: 18 | - **Kernel modules** - Hardware support and system features 19 | - **System utilities** - Command-line tools and daemons 20 | - **Libraries** - Shared code for applications 21 | 22 | ### Build and Configuration (Shell) 23 | Automation and system configuration: 24 | - **ghostbsd-build** - ISO building system 25 | - **Installation scripts** - System setup and configuration 26 | - **Package building** - Port compilation and packaging 27 | 28 | ## Getting Started with Code 29 | 30 | ### First Steps 31 | **[Development Environment Setup](development-setup)** – **Start here!** Set up your development machine, install tools, and configure your environment for GhostBSD development. 32 | 33 | ### Development Guides 34 | - [Python Development Guide](python-guide) – Python coding standards, typing, and GTK3 development 35 | - [C Development Guide](c-guide) – Working with system components 36 | - [Shell Scripting Guide](shell-guide) – Build tools and configuration scripts 37 | - [Testing and QA](testing) – How to test your changes 38 | - [Code Standards](standards) – Coding style and best practices -------------------------------------------------------------------------------- /contributor/community/users-support.md: -------------------------------------------------------------------------------- 1 | # Users Support 2 | 3 | Helping other users is a great way to contribute back, and it helps developers to focus on working on GhostBSD bugs and new features. Anyone with reasonable Linux/BSD experience and English skills can help. 4 | 5 | ## Users Support platform 6 | 7 | There are many platform where users may ask for support: 8 | 9 | * On [Forum topics](https://forums.ghostbsd.org/index.php) 10 | * On [Telegram Group](https://t.me/ghostbsd) 11 | * On [Element(Matrix) rooms](https://app.element.io/#/room/#ghostbsd:libera.chat) 12 | * On [#ghostbsd IRC Libera Chat](irc://irc.libera.chat:6697/ghostbsd) 13 | * On [Reddit](https://www.reddit.com/r/GhostBSD/) 14 | 15 | :::{note} 16 | GhostBSD Telegram Group is connected to the GhostBDS IRC channel with Matrix Telegram Bridge so only one messaging platform is needed to help Users on the tree messaging platform. 17 | ::: 18 | 19 | Feel free to track any platform where you feel you may be able to help users. 20 | 21 | 22 | ## User Support Resources 23 | 24 | When helping users, is good to be familiar with certain help resources yourself, so that you can simply point users to the right resource when possible: 25 | 26 | * [Documentation Hub](https://ghostbsd-documentation-portal.readthedocs.io/en/latest/index.html) 27 | * [GhostBSD Wiki](https://wiki.ghostbsd.org/index.php/Main_Page) 28 | * [FreeBSD Handbook](https://docs.freebsd.org/en/books/handbook/) 29 | * [FreeBSD Wiki](https://wiki.freebsd.org/) 30 | 31 | 32 | ## Be a Welcoming helper 33 | 34 | Patience is a virtue. And like most virtues, sometimes it isn’t easy. Interacting online has its own challenges, and it can be a little too easy to dismiss people. But you could be the difference between someone who abandons GhostBSD because of a lack of friendly support, and someone who becomes an invested member of the community. So be respectful, be helpful, and be excellent to each other. -------------------------------------------------------------------------------- /contributor/community/users-support-pl.md: -------------------------------------------------------------------------------- 1 | # Wsparcie Użytkowników 2 | 3 | Pomaganie innym użytkownikom to doskonały sposób na wniesienie wkładu w projekt oraz pozwala programistom skupić się na rozwiązywaniu błędów i nowych funkcjach GhostBSD. Każdy z odpowiednim doświadczeniem w Linuxie/BSD i umiejętnościami językowymi w angielskim może pomóc. 4 | 5 | ## Platformy Wsparcia Użytkowników 6 | 7 | Istnieje wiele platform, na których użytkownicy mogą prosić o wsparcie: 8 | 9 | * Na [tematach na forum](https://forums.ghostbsd.org/index.php) 10 | * Na [grupie Telegram](https://t.me/ghostbsd) 11 | * Na [pokojach Element(Matrix)](https://app.element.io/#/room/#ghostbsd:libera.chat) 12 | * Na [IRC #ghostbsd w Libera Chat](irc://irc.libera.chat:6697/ghostbsd) 13 | * Na [Reddit](https://www.reddit.com/r/GhostBSD/) 14 | 15 | :::{note} 16 | Grupa Telegram GhostBSD jest połączona z kanałem IRC GhostBSD za pomocą Matrix Telegram Bridge, więc wystarczy jedna platforma komunikacyjna, aby pomagać użytkownikom na trzech platformach komunikacyjnych. 17 | ::: 18 | 19 | Śmiało śledź dowolną platformę, na której czujesz, że możesz pomóc użytkownikom. 20 | 21 | ## Zasoby Wsparcia Użytkowników 22 | 23 | Podczas pomagania użytkownikom warto być zaznajomionym z pewnymi zasobami, aby móc skierować użytkowników do odpowiednich źródeł, gdy to możliwe: 24 | 25 | * [Hub Dokumentacji](https://ghostbsd-documentation-portal.readthedocs.io/en/latest/index.html) 26 | * [Wiki GhostBSD](https://wiki.ghostbsd.org/index.php/Main_Page) 27 | * [Podręcznik FreeBSD](https://docs.freebsd.org/en/books/handbook/) 28 | * [Wiki FreeBSD](https://wiki.freebsd.org/) 29 | 30 | ## Bądź Przyjaznym Pomocnikiem 31 | 32 | Cierpliwość jest cnotą. I jak większość cnót, czasami nie jest łatwa do utrzymania. Interakcja online ma swoje wyzwania i czasami zbyt łatwo jest zlekceważyć ludzi. Możesz być różnicą między kimś, kto porzuca GhostBSD z powodu braku przyjaznego wsparcia, a kimś, kto staje się zaangażowanym członkiem społeczności. Dlatego bądź szanowany, pomocny i doskonały wobec siebie nawzajem. -------------------------------------------------------------------------------- /.github/workflows/project_automation.yml: -------------------------------------------------------------------------------- 1 | name: Project automations 2 | 3 | on: 4 | issues: 5 | types: 6 | - opened 7 | - assigned 8 | pull_request_target: 9 | types: 10 | - opened 11 | branches: 12 | - 'master' 13 | 14 | # map fields with customized labels 15 | env: 16 | new: New 17 | todo: Todo 18 | done: Done 19 | in_progress: In Progress 20 | in_review: In Review 21 | 22 | jobs: 23 | issue_opened: 24 | name: issue_opened 25 | runs-on: ubuntu-latest 26 | if: github.event_name == 'issues' && (github.event.action == 'opened') 27 | steps: 28 | - name: Move issue to ${{ env.new }} 29 | uses: leonsteinhaeuser/project-beta-automations@v2.1.0 30 | with: 31 | gh_token: ${{ secrets.MY_GITHUB_TOKEN }} 32 | # user: ghostbsd 33 | organization: ghostbsd 34 | project_id: 5 35 | resource_node_id: ${{ github.event.issue.node_id }} 36 | status_value: ${{ env.new }} 37 | issue_assigned: 38 | name: issue_assigned 39 | runs-on: ubuntu-latest 40 | if: github.event_name == 'issues' && (github.event.action == 'assigned') 41 | steps: 42 | - name: Move issue to ${{ env.in_progress }} 43 | uses: leonsteinhaeuser/project-beta-automations@v2.1.0 44 | with: 45 | gh_token: ${{ secrets.MY_GITHUB_TOKEN }} 46 | # user: ghostbsd 47 | organization: ghostbsd 48 | project_id: 5 49 | resource_node_id: ${{ github.event.issue.node_id }} 50 | status_value: ${{ env.in_progress }} 51 | pr_opened: 52 | name: pr_opened 53 | runs-on: ubuntu-latest 54 | if: github.event_name == 'pull_request_target' && github.event.action == 'opened' 55 | steps: 56 | - name: Move PR to ${{ env.in_review }} 57 | uses: leonsteinhaeuser/project-beta-automations@v2.1.0 58 | with: 59 | gh_token: ${{ secrets.MY_GITHUB_TOKEN }} 60 | # user: ghostbsd 61 | organization: ghostbsd 62 | project_id: 5 63 | resource_node_id: ${{ github.event.pull_request.node_id }} 64 | status_value: ${{ env.in_review }} 65 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | Welcome to GhostBSD's documentation portal! 2 | =========================================== 3 | 4 | This documentation portal has all the information users need to get going with their journey using GhostBSD. It also contains information for people that want to help the community, report bugs, and contribute to the project. 5 | 6 | ## Overview 7 | 8 | GhostBSD is a simple, elegant, and friendly BSD operating system for desktops and laptops based on FreeBSD. GhostBSD is a slow-rolling release while some GNU/Linux distros are on the bleeding edge side; we tried to offer a stable update and release cycle. The official desktop environment is MATE. The system comes with a graphical application to install software and update your system. Most codecs to play multimedia files are pre-installed. The installer leverages OpenZFS makes it easy to install and is suitable for newcomers to BSD. With modest hardware requirements, GhostBSD is ideal for modern workstations and 64-bit single-board computer hardware. 9 | 10 | ## Our Goal 11 | 12 | In general, BSD is also considered beyond the average computer user's knowledge. We try to simplify FreeBSD to lower the entry-level of using FreeBSD on a desktop or laptop. We provide all the benefits of the FreeBSD operating system benefits combined with our in-house GUI tool. 13 | 14 | 15 | ```{toctree} 16 | :caption: User Documentation 17 | :hidden: 18 | 19 | user/installation-guide/installation-guide 20 | user/upgrading-guide 21 | user/security-key 22 | user/FAQ 23 | ``` 24 | 25 | 26 | ```{toctree} 27 | :caption: Contributor Documentation 28 | :maxdepth: 2 29 | :hidden: 30 | 31 | contributor/index 32 | contributor/getting-started/index 33 | contributor/code/index 34 | contributor/maintenance-release/index 35 | contributor/documentation/index 36 | contributor/translations/index 37 | contributor/community/index 38 | ``` 39 | 40 | 41 | ```{toctree} 42 | :caption: Upstream Documentation 43 | :maxdepth: 2 44 | :hidden: 45 | MATE Documentation 46 | FreeBSD Documentation 47 | FreeBSD Handbook 48 | FreeBSD Wiki 49 | ``` 50 | 51 | 52 | ```{toctree} 53 | :caption: Legal Documentation 54 | :maxdepth: 2 55 | :hidden: 56 | 57 | legal/license 58 | legal/trademark 59 | ``` 60 | -------------------------------------------------------------------------------- /user/installation-guide/troubleshooting.md: -------------------------------------------------------------------------------- 1 | Troubleshooting 2 | =============== 3 | 4 | ## The live system does not boot. 5 | 6 | ### If Secure Boot is enabled, in BIOS settings for your computer, disable it. 7 | 8 | Support for Secure Boot is [not yet integral to FreeBSD](https://wiki.freebsd.org/SecureBoot). 9 | 10 | ### Your hardware may not be supported. 11 | 12 | GhostBSD is based on [the STABLE branch](https://www.freebsd.org/where/#helptest) of FreeBSD. 13 | Hardware support is generally good, however, there may be issues with some modern hardware. 14 | 15 | To determine whether the issue relates to hardware, or to the USB drive: 16 | 17 | - try to boot from the same drive on a different computer. 18 | 19 | For information about hardware components, please see FreeBSD information for the _RELEASE_ that corresponds to the version of _STABLE_ used by GhostBSD. 20 | 21 | You can run `ghostbsd-version -kv` to show the version number. As an example, _**14**0**1**502_ was from the _14.1-STABLE_ branch, and **hardware information** is amongst the pages at . 22 | 23 | ### The installation media may be corrupted. 24 | 25 | Corruption may occur during download of an installer image file, or during creation of a bootable USB flash drive. 26 | Please refer to the [Getting started](getting-started.md) guide to download a new image and create a new bootable USB flash drive. 27 | 28 | ## The live system does not reach a graphical desktop environment. 29 | 30 | ### GhostBSD automated configuration does not support some dual-GPU configurations. 31 | 32 | Symptoms may include: 33 | 34 | - _Setting up (Intel DRM).. Please wait.._ -- on screen, no progress beyond this line 35 | - a mostly black screen -- a white rectangle in the upper left corner, with a pointer that can not be moved. 36 | 37 | Auto-config (kernel modules, other graphics drivers, X.Org) may fail with, for example: 38 | 39 | - computers that support [NVIDIA Optimus](https://en.wikipedia.org/wiki/Nvidia_Optimus) 40 | - some dual-GPU Macs. 41 | 42 | If your computer BIOS allows one of two GPUs to be disabled: please make this setting before your next attempt to boot the live system. 43 | 44 | Users of affected Apple hardware may find it impossible to set the Mac to use a single GPU. 45 | 46 | 47 | ### … 48 | 49 | Please note: this section is incomplete. 50 | -------------------------------------------------------------------------------- /contributor/getting-started/index.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | Welcome to the GhostBSD contributor community! Whether you're a developer, designer, writer, translator, or just want to help users, there's a place for you here. 4 | 5 | ## Ways to Contribute 6 | 7 | ### 🔧 Development & Technical 8 | - **[Code Contribution](../code/index)** – Develop applications, system tools, and build scripts 9 | - Start with **[Development Setup](../code/development-setup)** to configure your environment 10 | - **[Maintenance & Release](../maintenance-release/index)** – Help maintain ports, packages, and releases 11 | 12 | ### 📝 Content & Community 13 | - **[Documentation](../documentation/index)** – Write and improve user and developer documentation 14 | - **[Translations](../translations/index)** – Help translate GhostBSD into more languages 15 | - **[Community Support](../community/index)** – Help users and grow our community 16 | 17 | ## Requirements for All Contributors 18 | 19 | ### Communication in English 20 | Our contributors come from around the world, and English is our common language. You don't need to be fluent, but you should be comfortable understanding and communicating ideas effectively. 21 | 22 | ### Familiarity with Git and GitHub 23 | We use Git for version control and GitHub for collaboration. You'll need: 24 | - A **[GitHub account](https://github.com/)** to contribute 25 | - Basic **Git knowledge** (commits, branches, pull requests) - see [GitHub Docs](https://docs.github.com/en/get-started/start-your-journey) if you're new to Git 26 | 27 | ### Running GhostBSD (Recommended) 28 | For the best contribution experience, run the latest stable GhostBSD. Download from [ghostbsd.org/download](https://www.ghostbsd.org/download) - works on physical machines or virtual environments. 29 | 30 | ## Essential Information 31 | 32 | - **[Contributors Guide](ghostbsd-contributors-guide)** – Essential information for all contributors 33 | - **[Contributor Levels](contributor-levels)** – Understanding project roles from New Contributors to Project Leader 34 | 35 | ## Ready to Jump In? 36 | 37 | - Browse our [project roadmap](https://github.com/orgs/ghostbsd/projects/4) to see what we're working on 38 | - Check the [issue tracker](https://github.com/orgs/ghostbsd/projects/4/views/21) for tasks that need help 39 | - Join our [Telegram developer group](https://t.me/ghostbsd_dev) to introduce yourself -------------------------------------------------------------------------------- /index-pl.md: -------------------------------------------------------------------------------- 1 | Witaj w portalu dokumentacyjnym GhostBSD! 2 | ========================================= 3 | 4 | Ten portal dokumentacyjny zawiera wszystkie informacje, których użytkownicy potrzebują, aby rozpocząć swoją przygodę z GhostBSD. Zawiera również informacje dla osób, które chcą pomóc społeczności, zgłaszać błędy i przyczynić się do projektu. 5 | 6 | ## Przegląd 7 | 8 | GhostBSD to prosty, elegancki i przyjazny system operacyjny BSD dla komputerów stacjonarnych i laptopów oparty na FreeBSD. GhostBSD jest wersją slow-rolling, podczas gdy niektóre dystrybucje GNU/Linux są na krawędzi nowinek; staramy się oferować stabilny cykl aktualizacji i wydań. Oficjalne środowisko graficzne to MATE. System wyposażony jest w graficzną aplikację do instalacji oprogramowania i aktualizacji systemu. Większość kodeków do odtwarzania plików multimedialnych jest preinstalowana. Instalator wykorzystuje OpenZFS, co ułatwia instalację i jest odpowiednie dla nowicjuszy w świecie BSD. Przy umiarkowanych wymaganiach sprzętowych, GhostBSD jest idealnym rozwiązaniem dla nowoczesnych stacji roboczych i sprzętu komputerowego z jednoprocesorową płytą. 9 | 10 | ## Nasz cel 11 | 12 | Generalnie, BSD jest również uważane za wykraczające poza przeciętną wiedzę użytkowników komputerów. Staramy się uprościć FreeBSD, aby obniżyć próg wejścia w korzystanie z FreeBSD na komputerze stacjonarnym lub laptopie. Oferujemy wszystkie korzyści systemu operacyjnego FreeBSD połączone z naszym własnym narzędziem GUI. 13 | 14 | ```{toctree} 15 | :caption: Dokumentacja użytkownika 16 | :hidden: 17 | 18 | user/installation-guide/installation-guide 19 | user/upgrading-guide 20 | user/FAQ 21 | ``` 22 | 23 | 24 | ```{toctree} 25 | :caption: Dokumentacja dla współpracowników 26 | :maxdepth: 2 27 | :hidden: 28 | 29 | contributor/index 30 | contributor/getting-started/index 31 | contributor/ports/index 32 | contributor/contributor-levels-pl 33 | contributor/ghostbsd-contributors-guide-pl 34 | ``` 35 | 36 | 37 | ```{toctree} 38 | :caption: Dokumentacja upstream 39 | :maxdepth: 2 40 | :hidden: 41 | MATE Documentation 42 | FreeBSD Documentation 43 | FreeBSD Handbook 44 | FreeBSD Wiki 45 | ``` 46 | 47 | 48 | ```{toctree} 49 | :caption: Dokumentacja prawna 50 | :maxdepth: 4 51 | :hidden: 52 | 53 | legal/license 54 | legal/trademark 55 | ``` -------------------------------------------------------------------------------- /contributor/documentation/getting-started-pl.md: -------------------------------------------------------------------------------- 1 |

Wkład w Dokumentację

2 | 3 | Pisanie dokumentacji to świetny sposób na poprawę doświadczeń użytkowników GhostBSD, a także ogromna pomoc dla wielu użytkowników GhostBSD, którzy chcą lepiej zrozumieć swój pulpit i aplikacje. Każdy, kto ma dobre umiejętności językowe w języku angielskim oraz dobrą znajomość FreeBSD, GhostBSD lub MATE, może pomóc. 4 | 5 | ## Komunikacja z zespołem 6 | 7 | Istnieje wiele sposobów na skontaktowanie się z zespołem: 8 | * Grupa [GhostBSD Dev](https://t.me/ghostbsd_dev) na Telegramie 9 | * Kanał [#ghostbsd-dev:libera.chat](https://app.element.io/#/room/#ghostbsd-dev:libera.chat) na Matrix 10 | * #ghostbsd-dev na IRC Libera Chat 11 | 12 | Te trzy platformy komunikacyjne są ze sobą połączone. Bez względu na to, czy używasz IRC, Telegramu czy Matrix, będziesz połączony ze wszystkimi platformami komunikacyjnymi. 13 | 14 | ## Uzyskiwanie zasobów 15 | 16 | Aby dokumentować projekty GhostBSD, warto uruchomić [najnowszą wersję GhostBSD](https://www.ghostbsd.org/download#latest_builds), a do dokumentowania projektów innych firm potrzebna będzie również najnowsza wersja tego programu. Używamy [Sphinx](https://www.sphinx-doc.org) z [MyST](https://myst-parser.readthedocs.io), co ułatwia tworzenie naszego Centrum Dokumentacji. Każdy, kto chce pomóc, powinien zacząć zapoznawać się z [Git](getting-started/getting-started.md#knowing-how-to-use-git), [GitHub](getting-started/getting-started.md#knowing-how-to-use-github) i [MyST Markdown syntax](https://myst-parser.readthedocs.io/en/latest/intro.html). 17 | 18 | Instrukcje dotyczące instalacji i konfiguracji można znaleźć w repozytorium [GhostBSD Documentation GitHub](https://github.com/ghostbsd/documentation#local-development-server). 19 | 20 | ## Zadania 21 | 22 | Możesz zacząć swoje pierwsze wkłady już dziś! Oto kilka zadań dla początkujących: 23 | * Przeczytaj dokumentację i jeśli znajdziesz błędy gramatyczne, popraw je 24 | * Popraw zdania i akapity 25 | * Aktualizuj zrzuty ekranu i dokumentację 26 | * Twórz zgłoszenia na naszej stronie [GitHub Documentation Issues](https://github.com/ghostbsd/documentation/issues/new). 27 | 28 | Zadania i problemy można również znaleźć w naszej [Documentation Management](https://github.com/orgs/ghostbsd/projects/5) na GitHubie. 29 | 30 | Jeśli zauważysz artykuł na [Wiki](https://wiki.ghostbsd.org/), który mógłby być przeniesiony, skomunikuj się z innymi w czacie deweloperów GhostBSD. -------------------------------------------------------------------------------- /contributor/getting-started/contributor-levels.md: -------------------------------------------------------------------------------- 1 | GhostBSD Contributor Levels 2 | =========================== 3 | 4 | ## 1. New Contributors 5 | **Description:** New members who are actively contributing to the project. 6 | 7 | **Access and Permissions:** Access to public repositories with full capabilities to create branches and submit pull requests. 8 | 9 | **Responsibilities:** 10 | * Complete assigned tasks and participate in the project. 11 | * Engage in code reviews and discussions to enhance project quality. 12 | * Pair with a mentor or a more experienced team member for continuous guidance and growth. 13 | 14 | ## 2. Contributors 15 | **Description:** Members who have consistently contributed and strongly understand the project workflow. 16 | 17 | **Access and Permissions:** Full access to all repositories with the ability to create branches and submit pull requests. 18 | 19 | **Responsibilities:** 20 | * Develop new features and resolve issues. 21 | * Review and commit changes from Junior Contributors and peers. 22 | * Maintain and enhance project documentation. 23 | * Communicate regularly with Core Contributors for guidance and feedback. 24 | 25 | ## 3. Core Contributors 26 | 27 | **Description:** Long-time contributors with significant contributions and comprehensive knowledge of the project. 28 | 29 | **Access and Permissions:** Complete access and permission to all repositories, including creating new ones and participating in decision-making processes. 30 | 31 | **Responsibilities:** 32 | * Lead major projects and strategic initiatives. 33 | * Mentor Junior Contributors and other members. 34 | * Make key decisions on project direction and policies. 35 | * Ensure high code quality and adherence to project standards. 36 | * Meet regularly with the Project Leader to discuss progress, challenges, and strategic goals. 37 | 38 | ## 4. Project Leader 39 | **Description:** The overall leader and visionary for the project. 40 | 41 | **Access and Permissions:** Complete administrative access and authority to make final decisions. 42 | 43 | **Responsibilities:** 44 | * Set the vision and direction for the project. 45 | * Oversee the entire development process. 46 | * Foster community engagement and manage external relations. 47 | * Ensure resources and support are available for all team members. 48 | * Collaborate with Core Contributors and external advisors to align the project with broader community and technological trends. 49 | -------------------------------------------------------------------------------- /contributor/getting-started/contributor-levels-pl.md: -------------------------------------------------------------------------------- 1 | Poziomy Współpracowników GhostBSD 2 | ================================== 3 | 4 | ## 1. Młodsi Współpracownicy 5 | **Opis:** Nowi członkowie, którzy aktywnie przyczyniają się do projektu. 6 | **Dostęp i Uprawnienia:** Dostęp do publicznych repozytoriów z pełnymi możliwościami tworzenia gałęzi i przesyłania pull requestów. 7 | 8 | **Obowiązki:** 9 | * Wykonywanie przydzielonych zadań i uczestnictwo w projekcie. 10 | * Udział w przeglądach kodu i dyskusjach w celu podniesienia jakości projektu. 11 | * Współpraca z mentorem lub bardziej doświadczonym członkiem zespołu w celu ciągłego wsparcia i rozwoju. 12 | 13 | ## 2. Współpracownicy 14 | **Opis:** Członkowie, którzy konsekwentnie przyczyniają się do projektu i dobrze rozumieją jego przepływ pracy. 15 | **Dostęp i Uprawnienia:** Pełny dostęp do wszystkich repozytoriów z możliwością tworzenia gałęzi i przesyłania pull requestów. 16 | 17 | **Obowiązki:** 18 | * Opracowywanie nowych funkcji i rozwiązywanie problemów. 19 | * Przeglądanie i zatwierdzanie zmian od Młodszych Współpracowników i rówieśników. 20 | * Utrzymywanie i udoskonalanie dokumentacji projektu. 21 | * Regularna komunikacja z Głównymi Współpracownikami w celu uzyskania wskazówek i opinii. 22 | 23 | ## 3. Główni Współpracownicy 24 | 25 | **Opis:** Długoletni współpracownicy z znaczącym wkładem i wszechstronną znajomością projektu. 26 | **Dostęp i Uprawnienia:** Pełny dostęp i uprawnienia do wszystkich repozytoriów, w tym możliwość tworzenia nowych i udziału w procesach decyzyjnych. 27 | 28 | **Obowiązki:** 29 | * Prowadzenie głównych projektów i inicjatyw strategicznych. 30 | * Mentorowanie Młodszych Współpracowników i innych członków. 31 | * Podejmowanie kluczowych decyzji dotyczących kierunku i polityki projektu. 32 | * Zapewnienie wysokiej jakości kodu i przestrzegania standardów projektu. 33 | * Regularne spotkania z Liderem Projektu w celu omówienia postępów, wyzwań i celów strategicznych. 34 | 35 | ## 4. Lider Projektu 36 | **Opis:** Ogólny lider i wizjoner projektu. 37 | **Dostęp i Uprawnienia:** Pełny dostęp administracyjny i uprawnienia do podejmowania ostatecznych decyzji. 38 | 39 | **Obowiązki:** 40 | * Określanie wizji i kierunku projektu. 41 | * Nadzór nad całym procesem rozwoju. 42 | * Wspieranie zaangażowania społeczności i zarządzanie relacjami zewnętrznymi. 43 | * Zapewnienie zasobów i wsparcia dla wszystkich członków zespołu. 44 | * Współpraca z Głównymi Współpracownikami i zewnętrznymi doradcami w celu dostosowania projektu do szerszych trendów społecznych i technologicznych. -------------------------------------------------------------------------------- /contributor/documentation/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started with Documentation 2 | 3 | Ready to contribute to GhostBSD documentation? This guide will help you get started with writing, editing, and improving our documentation to make GhostBSD more accessible to everyone. 4 | 5 | Writing documentation is a great way to start improving GhostBSD user experience, and you will be helping a lot of GhostBSD users to better understand their desktop and applications. Anyone with reasonable English skills and good knowledge of FreeBSD, GhostBSD or MATE can help. 6 | 7 | ## Prerequisites 8 | 9 | Before contributing to documentation, make sure you've covered the [general contributor requirements](../getting-started/index#requirements-for-all-contributors) including Git, GitHub account, and familiarity with basic version control concepts. 10 | 11 | ## Communicating with the team 12 | 13 | Get in touch with the team through our [GhostBSD Contributors](https://t.me/ghostbsd_dev) Group on Telegram. 14 | 15 | ## Getting the resources 16 | 17 | To document GhostBSD projects, you will want to run a [recent GhostBSD release](https://www.ghostbsd.org/download), and to document third-party projects, you will also need a recent version of that program. We use [Sphinx](https://www.sphinx-doc.org) with [MyST](https://myst-parser.readthedocs.io) to make it easy to create our Documentation Hub. You should also get familiar with [MyST Markdown syntax](https://myst-parser.readthedocs.io/en/latest/intro.html). 18 | 19 | ## Setting up the Documentation Environment 20 | 21 | 1. **Clone the documentation repository:** 22 | ```bash 23 | git clone https://github.com/ghostbsd/documentation.git 24 | cd documentation 25 | ``` 26 | 27 | 2. **Install Python dependencies:** 28 | ```bash 29 | sudo pkg install -y py311-pip 30 | sudo pip install -r requirements.txt 31 | ``` 32 | 33 | 3. **Start the development server:** 34 | ```bash 35 | sphinx-autobuild . build/html 36 | ``` 37 | 38 | 4. **View your work:** Open http://127.0.0.1:8000/index.html in your browser. It will automatically refresh when you save changes. 39 | 40 | ## Tasks 41 | 42 | You can get your first contribution committed today! Here are some tasks for beginners: 43 | * Read the documentation if there is a grammar issue, fix it 44 | * Improve the sentences and paragraphs 45 | * Update ScreenShots and Documentation 46 | * Create issues on our [GitHub Documentation Issues](https://github.com/ghostbsd/documentation/issues/new). 47 | 48 | There are also tasks and issues that can be found at our [Documentation Management](https://github.com/orgs/ghostbsd/projects/5) on GitHub. 49 | 50 | If you see any article from the [Wiki](https://wiki.ghostbsd.org/) that could be ported, communicate the effort with the others in the GhostBSD dev chat. -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 | 7 | # -- Path setup -------------------------------------------------------------- 8 | 9 | # If extensions (or modules to document with autodoc) are in another directory, 10 | # add these directories to sys.path here. If the directory is relative to the 11 | # documentation root, use os.path.abspath to make it absolute, like shown here. 12 | # 13 | import os 14 | # import sys 15 | # sys.path.insert(0, os.path.abspath('.')) 16 | 17 | # -- Project information ----------------------------------------------------- 18 | 19 | project = 'GhostBSD' 20 | copyright = '2025, GhostBSD' 21 | author = 'Eric Turgeon' 22 | 23 | 24 | # -- General configuration --------------------------------------------------- 25 | 26 | # Add any Sphinx extension module names here, as strings. They can be 27 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 28 | # ones. 29 | extensions = [ 30 | 'myst_parser', 31 | 'sphinx_rtd_theme' 32 | ] 33 | 34 | myst_heading_anchors = 3 35 | 36 | myst_enable_extensions = [ 37 | 'colon_fence', 38 | 'attrs_inline', 39 | 'linkify' 40 | ] 41 | 42 | # Configure linkify to only auto-link www.* and https://* patterns 43 | myst_linkify_fuzzy_links = False 44 | myst_url_schemes = ["https", "http"] 45 | 46 | master_doc = 'index' 47 | 48 | source_suffix = [".md"] 49 | 50 | # Add any paths that contain templates here, relative to this directory. 51 | templates_path = ['_templates'] 52 | 53 | # List of patterns, relative to source directory, that match files and 54 | # directories to ignore when looking for source files. 55 | # This pattern also affects html_static_path and html_extra_path. 56 | exclude_patterns = ['README.md'] 57 | pygments_style = 'default' 58 | 59 | 60 | # -- Options for HTML output ------------------------------------------------- 61 | 62 | # The theme to use for HTML and HTML Help pages. See the documentation for 63 | # a list of builtin themes. 64 | # 65 | html_theme = 'sphinx_rtd_theme' 66 | 67 | # Display "Edit on GitHub" 68 | html_context = { 69 | 'display_github': True, 70 | 'github_user': 'ghostbsd', 71 | 'github_repo': 'documentation', 72 | 'github_version': 'master/', 73 | } 74 | 75 | html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] } 76 | 77 | # Add any paths that contain custom static files (such as style sheets) here, 78 | # relative to this directory. They are copied after the builtin static files, 79 | # so a file named "default.css" will overwrite the builtin "default.css". 80 | html_static_path = ['_static'] 81 | html_css_files = ['dark_mode.css'] 82 | html_js_files = ['dark_mode.js'] 83 | -------------------------------------------------------------------------------- /contributor/maintenance-release/versioning-guide.md: -------------------------------------------------------------------------------- 1 | # GhostBSD Versioning Guide 2 | 3 | ## Overview 4 | GhostBSD uses a versioning scheme that clearly indicates which FreeBSD release it's based on, making it easier to track compatibility and updates. 5 | 6 | ## Versioning Format 7 | 8 | The GhostBSD version format is: **`YY.PP.R##.#p#`** 9 | 10 | ### Components Breakdown: 11 | - **`YY`**: Last two digits of the year (e.g., `25` for 2025) 12 | - **`PP`**: GhostBSD patch version (incremental: `01`, `02`, `03`, etc.) 13 | - **`R`**: Indicates this is a RELEASE version 14 | - **`##.#`**: FreeBSD major and minor version (e.g., `14.2`) 15 | - **`p#`**: FreeBSD patch level (`p0`, `p1`, `p2`, etc.) 16 | 17 | ### Example: 18 | **`25.01.R14.2p1`** means: 19 | - Released in **2025** 20 | - **First** GhostBSD patch version of the year (`01`) 21 | - Based on FreeBSD **RELEASE** 22 | - Uses FreeBSD **14.2** base 23 | - Includes FreeBSD patch level **p1** 24 | 25 | --- 26 | 27 | ## Version Examples 28 | 29 | | GhostBSD Version | Release Year | Notes | 30 | |------------------|--------------|-------| 31 | | `25.01.R14.2p0` | 2025 | Based on initial 14.2 release | 32 | | `25.01.R14.2p1` | 2025 | First patch level update | 33 | | `25.02.R14.2p2` | 2025 | Updated for security patches | 34 | | `25.03.R14.3p0` | 2025 | New FreeBSD minor version | 35 | 36 | --- 37 | 38 | ## Checking GhostBSD Version 39 | 40 | ```bash 41 | # Check GhostBSD version 42 | ghostbsd-version 43 | 44 | # Direct file check 45 | cat /etc/version 46 | ``` 47 | 48 | --- 49 | 50 | ## Version Files in ghostbsd-src 51 | 52 | ### Key Version File: 53 | - **`sys/conf/package-version`**: Contains the GhostBSD version string 54 | 55 | ### Version Flow: 56 | 1. `sys/conf/package-version` contains the GhostBSD version string 57 | 2. Build process uses this to create `/etc/version` in the final system 58 | 3. `ghostbsd-version` command reads `/etc/version` 59 | 60 | --- 61 | 62 | ## Release Lifecycle 63 | 64 | ### Regular Release Cycle: 65 | 1. **Update to new FreeBSD base** 66 | 2. **Testing and integration** of GhostBSD-specific features 67 | 3. **Update `sys/conf/package-version`** with new GhostBSD version 68 | 4. **Build and test** complete system 69 | 5. **Release** with updated version number 70 | 71 | ### Update Types: 72 | - **Patch level updates**: Update FreeBSD patch (e.g., `25.01.R14.2p0` → `25.01.R14.2p1`) 73 | - **GhostBSD updates**: Increment GhostBSD patch version (e.g., `25.01.R14.2p1` → `25.02.R14.2p1`) 74 | 75 | --- 76 | 77 | ## Branch Correlation 78 | 79 | ### Repository Branches vs. Versions: 80 | 81 | | Repository Branch | GhostBSD Version Pattern | 82 | |-------------------|-------------------------| 83 | | `main` | Development builds | 84 | | `stable/14` | Not released | 85 | | `releng/14.2` | `25.01.R14.2p0`, `25.01.R14.2p1` | 86 | | `releng/14.3` | `25.03.R14.3p0` | 87 | 88 | --- 89 | 90 | ## Developer Guidelines 91 | 92 | ### When Creating Releases: 93 | 1. **Update `sys/conf/package-version`**: Set the new GhostBSD version 94 | 2. **Test version commands**: Verify `ghostbsd-version` returns correct value 95 | 3. **Build and test**: Complete system build and testing 96 | 4. **Document changes**: Note any GhostBSD-specific modifications 97 | 98 | ### Version Verification: 99 | ```bash 100 | # After building, verify version is correct 101 | ghostbsd-version # Should show new GhostBSD version 102 | ``` -------------------------------------------------------------------------------- /contributor/maintenance-release/maintaining-ports-tree.md: -------------------------------------------------------------------------------- 1 | # Maintaining GhostBSD Ports from FreeBSD Ports 2 | 3 | ## Purpose 4 | This guide explains how to keep the GhostBSD ports tree (https://github.com/ghostbsd/ghostbsd-ports) current with the upstream FreeBSD ports tree (https://github.com/freebsd/freebsd-ports), resolve merge conflicts, and test changes before submission. 5 | 6 | ## Prerequisites 7 | - Git installed and configured with access to GitHub. 8 | - Basic understanding of Git commands and FreeBSD ports structure. 9 | - `poudriere` installed for testing (optional but recommended). 10 | - A local working directory (e.g., `~/ghostbsd-ports`). 11 | 12 | --- 13 | 14 | ## Step-by-Step Instructions 15 | 16 | ### 1. Clone the Repository and Configure Remotes 17 | Clone the GhostBSD ports repository if you don’t already have it: 18 | ```shell 19 | git clone git@github.com:ghostbsd/ghostbsd-ports.git 20 | cd ghostbsd-ports 21 | ``` 22 | Add the FreeBSD ports repository as a remote: 23 | ```shell 24 | git remote add freebsd https://github.com/freebsd/freebsd-ports.git 25 | ``` 26 | Verify the remotes: 27 | ```shell 28 | git remote -v 29 | ``` 30 | Expected output: 31 | ``` 32 | freebsd https://github.com/freebsd/freebsd-ports.git (fetch) 33 | freebsd https://github.com/freebsd/freebsd-ports.git (push) 34 | origin https://github.com/ghostbsd/ghostbsd-ports.git (fetch) 35 | origin https://github.com/ghostbsd/ghostbsd-ports.git (push) 36 | ``` 37 | 38 | **Note**: If the `freebsd` remote is already set, skip the `git remote add` step. 39 | 40 | --- 41 | 42 | ### 2. Create a New Working Branch 43 | Always work in a feature branch to keep `main` clean: 44 | ```shell 45 | git checkout master 46 | git pull origin master # Ensure your local master is up-to-date 47 | git checkout -b my-branch-name 48 | ``` 49 | - Replace `my-branch-name` with a descriptive name (e.g., `sync-freebsd-20250403`). 50 | - This isolates your changes and simplifies pull requests. 51 | 52 | --- 53 | 54 | ### 3. Fetch and Merge FreeBSD Ports 55 | Fetch the latest changes from FreeBSD: 56 | ```shell 57 | git fetch freebsd 58 | ``` 59 | Merge FreeBSD’s `main` branch into your branch: 60 | ```shell 61 | git merge freebsd/main 62 | ``` 63 | 64 | - **If no conflicts occur**: Proceed to Step 5 (Testing). 65 | - **If conflicts occur**: Continue to Step 4 (Resolving Conflicts). 66 | --- 67 | 68 | ### 4. Resolve Merge Conflicts 69 | Conflicts typically come from GhostBSD-specific changes (e.g., `Mk` files, `Makefiles`). FreeBSD updates, like renamed or removed directories, can also affect merges. Check https://github.com/freebsd/freebsd-ports for upstream changes. To find code conflicts: 70 | ```bash 71 | grep -R '<<<<<<< HEAD' . 72 | ``` 73 | This lists files with conflicts, marked like: 74 | ``` 75 | <<<<<<< HEAD 76 | # GhostBSD-specific changes (your code) 77 | ======= 78 | # FreeBSD changes (upstream code) 79 | >>>>>>> freebsd/master 80 | ``` 81 | 82 | **Resolution Tips**: 83 | - Code conflicts require ports maintenance knowledge but are usually easy—often just changes Git can’t auto-merge. 84 | - **Keep GhostBSD changes**: Always preserve our customizations (e.g., in `Mk` files or `Makefiles`, the most common conflict sources), especially fixes made before FreeBSD or changes to default options. 85 | - **Resolve `PORTVERSION` conflicts**: For `Makefile` `PORTVERSION`, use FreeBSD’s version (e.g., `1.2.4`) unless a comment above ours (e.g., `# Keep 1.2.3 for GhostBSD fix`) says to keep it. 86 | - **Handle directory conflicts**: If FreeBSD renamed or removed a directory, ensure all files are moved to the new location and remove the old directory (use `git status` to spot added/removed files). 87 | 88 | ### 5. Test the Ports Tree (Dry Run) 89 | Before committing, test the updated ports tree with `poudriere`: 90 | ```shell 91 | sudo poudriere bulk -j ghostbsd-amd64 -p ghostbsd-ports -an 92 | ``` 93 | - `-j ghostbsd-amd64`: Specifies the jail (adjust if different). 94 | - `-p ghostbsd-ports`: Uses your local ports tree. 95 | - `-an`: Dry run (analyzes without building). 96 | 97 | Check the output for errors. If issues arise, fix the affected ports and repeat. 98 | 99 | ### 6. Commit and Push Changes 100 | Stage all changes: 101 | ```shell 102 | git add -A 103 | ``` 104 | Commit changes: 105 | ```shell 106 | git commit 107 | ``` 108 | Push to your branch: 109 | ```shell 110 | git push origin my-branch-name 111 | ``` 112 | 113 | ### 7. Submit Changes 114 | - Create a pull request (PR) on GitHub from `my-branch-name` to `ghostbsd-ports/master`. 115 | - Describe the changes and any resolved conflicts in the PR. 116 | - Await review and approval from maintainers. 117 | 118 | :::{note} 119 | Do not push directly to `master` unless you’re a maintainer with explicit permission. 120 | ::: 121 | 122 | ## Common Issues and Solutions 123 | - **Conflict in `Mk` Files**: FreeBSD may update build infrastructure. Retain GhostBSD-specific tweaks (e.g., custom `USES` flags). 124 | - **Renamed/Removed Directories**: If FreeBSD renamed or removed a directory, ensure all files are moved to the new location and delete the old directory during conflict resolution. 125 | - **Testing Fails**: Check `poudriere` logs (e.g., `/usr/local/poudriere/data/logs/bulk`) for clues. 126 | -------------------------------------------------------------------------------- /user/upgrading-guide.md: -------------------------------------------------------------------------------- 1 | Upgrading GhostBSD Guide 2 | ======================== 3 | 4 | ```{contents} Table of Contents 5 | :depth: 3 6 | :local: 7 | ``` 8 | 9 | ## Synopsis 10 | GhostBSD is under constant development and keeps in sync with the latest FreeBSD stable developments source code. However, upgrading GhostBSD to FreeBSD is not an option. GhostBSD provides Update Station to keep the system and all software up-to-date and allows easy upgrades between system versions. GhostBSD is a slow-rolling release meaning GhostBSD offers a stable release cycle and version increments on every system or software package build. This guide describes how to keep GhostBSD up-to-date. 11 | 12 | After reading this build, you will know the following: 13 | * How to keep a GhostBSD system up-to-date with Update Station. 14 | * How to keep a GhostBSD system up-to-date with pkg cli. 15 | 16 | ## GhostBSD upgrade with Update Station 17 | Applying security patches promptly and upgrading to a newer release of an operating system are important aspects of ongoing system administration. GhostBSD includes a GUI utility called Update Station, which performs both tasks. 18 | 19 | Update Station uses FreeBSD pkg to perform system and software updates, which have been made to update/upgrade GhostBSD properly. GhostBSD upgrades its base system using packages. Update Station will always upgrade you to the latest system and packages. If there is a kernel upgrade, it will reinstall all packages to ensure that there are no kernel mismatch issues with drivers and some software. 20 | 21 | This section demonstrates how to upgrade to the latest version and discusses some of the considerations when upgrading the operating system. 22 | 23 | ### Update notification 24 | On GhostBSD, you will receive a notification in the notification area, an orange icon will be visible when new software or system updates are available. Left Click on the icon, and a Window will open with the list of software and OS packages that will be upgraded. 25 | 26 | ![notification](upgrade-img/notification.png){.bg-primary align=center} 27 | 28 | ### Before upgrading 29 | On the Upgrade list, a checkbox at the bottom is enabled by default to create a boot environment backup before the upgrade. It is recommended to keep it enabled in case an issue happens with the upgrade. With a BE backup the system can be restored to the state it was before the upgrade was performed. 30 | 31 | ![upgrade_window](upgrade-img/upgrade_window.png){.bg-primary align=center} 32 | 33 | ### Starting the upgrade 34 | Click Install Upgrade to start the upgrade. 35 | 36 | ![upgrade_window](upgrade-img/upgrade_window.png){.bg-primary align=center} 37 | 38 | ### Update progress 39 | A window with a progress bar will appear. 40 | 41 | ![progress](upgrade-img/progress.png){.bg-primary align=center} 42 | 43 | ### Upgrade completed 44 | After the upgrade is complete Update Station will ask to restart the system if needed. 45 | 46 | ![completed](upgrade-img/completed.png){.bg-primary align=center} 47 | 48 | ## GhostBSD upgrade with pkg cli 49 | Upgrading packages with pkg has to be done in a specific way, specifically with OS upgrade. 50 | 51 | ### Before upgrading 52 | Before upgrading with pkg make sure to backup the system boot environment with **bectl**. It is recommended to backup the system boot environment in case an issue happens with the upgrade. With a BE backup the system can be restored to the state it was before the upgrade was performed. 53 | 54 | Here is an example on how to create BE. 55 | ```bash 56 | ericbsd@ericbsed-ghostbsd-pc ~> sudo bectl create upgrade-November-02-2023 57 | Password: 58 | ericbsd@ericbsed-ghostbsd-pc ~> sudo bectl list 59 | BE Active Mountpoint Space Created 60 | backup-2023-11-02-20-05 - - 68.5M 2023-11-02 20:05 61 | backup-2023-11-02-20-14 - - 109M 2023-11-02 20:14 62 | initial NR / 122G 2021-02-27 14:36 63 | new - - 44.4G 2023-05-22 15:18 64 | upgrade-November-02-2023 - - 1.07M 2023-11-02 20:50 65 | ericbsd@ericbsed-ghostbsd-pc ~> 66 | ``` 67 | 68 | ### Determining how to upgrade 69 | To determine how to upgrade packages with pkg, run **sudo pkg update -f** it will know if there is kernel mismatch. 70 | 71 | ```bash 72 | > sudo pkg update -f 73 | Updating GhostBSD repository catalogue... 74 | pkg: Repository GhostBSD has a wrong packagesite, need to re-create database 75 | Fetching meta.conf: 100% 163 B 0.2kB/s 00:01 76 | Fetching packagesite.pkg: 100% 7 MiB 6.9MB/s 00:01 77 | Processing entries: 0% 78 | Newer FreeBSD version for package ztrack: 79 | To ignore this error set IGNORE_OSVERSION=yes 80 | - package: 1302505 81 | - running kernel: 1301510 82 | Ignore the mismatch and continue? [y/N]: 83 | ``` 84 | 85 | If a similar message than the above one is encounter, **sudo pkg upgrade -f** must be used to upgrade all installed packages or some problem could occur after rebooting. If **sudo pkg update -f** doesn't report kernel mismatch, **sudo pkg upgrade** can be used to upgrade packages. 86 | 87 | ### Starting the upgrade 88 | Run the command below if there is a kernel mismatch with **update -f**. 89 | ``` 90 | sudo pkg upgrade -f 91 | ``` 92 | Run the command below if there no kernel mismatch with **update -f**. 93 | ``` 94 | sudo pkg upgrade 95 | ``` 96 | 97 | ### After the upgrade 98 | In most cases the system will need to be restarted after an upgrade. 99 | 100 | ## Troubleshooting 101 | 102 | **[Content coming soon]** 103 | -------------------------------------------------------------------------------- /contributor/code/development-setup.md: -------------------------------------------------------------------------------- 1 | # Development Environment Setup 2 | 3 | This guide will help you set up your development machine for contributing code to GhostBSD. Whether you want to work on Python applications, C system tools, or shell scripts, follow these steps to get started. 4 | 5 | ## Prerequisites 6 | 7 | Before setting up your development environment, make sure you've covered the [general contributor requirements](../getting-started/index#requirements-for-all-contributors) including Git, GitHub account, and preferably running GhostBSD. 8 | 9 | ## Technologies We Use 10 | Here’s a quick rundown of the tools and languages you’ll encounter in GhostBSD development. 11 | 12 | ### Programming Languages 13 | GhostBSD projects use a mix of languages depending on the task. You don’t need to master them all—just focus on what’s relevant to your interests. 14 | 15 | #### Python 16 | Most of our user-facing tools—like NetworkMgr, Update Station, and Software Station—are written in Python. It’s easy to learn, quick to develop with, and widely used in our ecosystem. 17 | 18 | #### C 19 | The FreeBSD base system (which GhostBSD builds upon) and many libraries are written in C. It’s a low-level language that requires more effort to work with but delivers excellent performance and deep system access. 20 | 21 | #### Bourne Shell (sh) 22 | Many scripts, including build tools like `ghostbsd-build` and utilities like `xconfig`, are written in Bourne shell script. It’s a lightweight way to automate tasks in the FreeBSD ecosystem. 23 | 24 | ### GUI Toolkit and Libraries 25 | Our graphical applications primarily use the [GTK3 toolkit](https://docs.gtk.org/gtk3/). We rely on GNOME libraries like GLib and GObject, often accessed through Python via [GObject Introspection](https://gi.readthedocs.io/). 26 | 27 | #### Configuration Tools 28 | We use `dconf` for storing system configuration. You can interact with it via the `gsettings` command-line tool or the graphical `dconf-editor`. 29 | 30 | Install `dconf-editor` for a visual interface: 31 | 32 | ```shell 33 | sudo pkg install dconf-editor 34 | ``` 35 | 36 | ## Setting Up Your Development Environment 37 | 38 | 39 | Let's get your machine ready for GhostBSD development. 40 | 41 | ### Install Development Tools 42 | 43 | #### Essential Development Packages 44 | Install the development toolkit and OS development packages: 45 | 46 | ```shell 47 | # Install development tools and utilities 48 | sudo pkg install ghostbsd-devel-tools 49 | 50 | # Install OS development packages (compilers, libraries, build tools) 51 | sudo pkg install -g 'GhostBSD*-dev' 52 | ``` 53 | 54 | The `ghostbsd-devel-tools` package provides commonly used development tools and utilities, while the `GhostBSD*-dev` packages include essential build tools, compilers, and libraries needed for system-level development. 55 | 56 | ### Create a Development Directory 57 | Organize your work in a dedicated directory. A common spot is your home directory: 58 | 59 | ```shell 60 | mkdir -p ~/projects/ghostbsd 61 | ```` 62 | 63 | Run cd `~/projects/ghostbsd` to jump in and start cloning repos. This keeps your repositories and files tidy. 64 | 65 | ### Development Tools 66 | #### Code Editors/IDEs 67 | Pick an editor or IDE you like—there’s no wrong choice! Here are some favorites: 68 | 69 | * **PyCharm Community Edition:** Perfect for Python tools like NetworkMgr with built-in linting and debugging. 70 | ```shell 71 | sudo pkg install pycharm-ce 72 | ``` 73 | * `Visual Studio Code:` Lightweight and extensible, great for general-purpose coding. 74 | ```shell 75 | sudo pkg install vscode 76 | ``` 77 | * `Sublime Text:` Fast and minimalist with great plugin support. 78 | ```shell 79 | sudo pkg install linux-sublime-text4 80 | ``` 81 | * `Neovim or Vim:` Lightweight for shell scripts or terminal fans. 82 | ```shell 83 | sudo pkg install neovim 84 | ``` 85 | 86 | For Python development, PyCharm stands out with built-in linting. If using another editor, set up a Pylint plugin (e.g., via VS Code’s marketplace or Sublime’s Package Control) to catch issues early. Try one that fits your style! 87 | 88 | #### Version Control Tools 89 | We use Git for version control. Beyond the command line, these graphical tools help: 90 | 91 | * **gitg:** A GTK-based interface to browse Git history. 92 | ```shell 93 | sudo pkg install gitg 94 | cd ~/projects/ghostbsd 95 | git clone https://github.com/ghostbsd/ghostbsd-ports.git 96 | cd ghostbsd-ports 97 | gitg 98 | ``` 99 | * **Sublime Merge:** A sleek Git client, pairs well with Sublime Text. 100 | ```shell 101 | sudo pkg install linux-sublime-merge 102 | ``` 103 | 104 | Clone a repo first (e.g., `git clone https://github.com/ghostbsd/ghostbsd-ports.git`) to explore with these. Many editors also have Git plugins—check yours! 105 | 106 | ### How to Contribute to GhostBSD 107 | 108 | We welcome all contributions! To get started, here's how to jump in: 109 | 110 | - **Check the Roadmap**: See our [releases roadmap](https://github.com/orgs/ghostbsd/projects/4) or [current sprint](https://github.com/orgs/ghostbsd/projects/4/views/22) for priorities. 111 | - **Find a Task**: Browse the [issue tracker](https://github.com/orgs/ghostbsd/projects/4/views/21) for bugs or small features, or check [documentation tasks](https://github.com/orgs/ghostbsd/projects/5/views/1) for writing opportunities. 112 | - **Submit Your Work**: Fork the repo, make changes, and send a pull request via GitHub. For docs, contribute to [ghostbsd/documentation](https://github.com/ghostbsd/documentation). 113 | - **Join Us**: Hop into our [Telegram group](https://t.me/ghostbsd_dev) for guidance or to say hi and share what you're working on! -------------------------------------------------------------------------------- /user/FAQ.md: -------------------------------------------------------------------------------- 1 | Frequently Asked Questions 2 | ========================== 3 | 4 | ```{contents} Table of Contents 5 | :depth: 3 6 | :local: 7 | ``` 8 | 9 | This document aims to cover the most frequently asked questions concerning the GhostBSD operating system. Although initially intended to reduce bandwidth and avoid the same old questions being asked repeatedly, FAQs have become recognized as valuable information resources. 10 | 11 | Every effort has been made to make this FAQ as informative as possible; if you have any suggestions about improving it, please feel for this GitHub and create a [Pull Request on GitHub](https://github.com/ghostbsd/documentation). 12 | 13 | ## Introduction 14 | 15 | ### What is GhostBSD? 16 | 17 | Briefly, GhostBSD is a UNIX®-like operating system. It works on AMD64 and Intel® platforms. GhostBSD is based on FreeBSD, which is based on U.C. Berkeley’s “4.4BSD-Lite” release, with some “4.4BSD-Lite2” enhancements. It is also based indirectly on Lynne and William Jolitz's port of U.C. Berkeley’s “Net/2” to the i386, known as “386BSD”, though very little of the 386BSD code remains. Currently, GhostBSD provides MATE desktop as the default version and a community release with XFCE desktop. 18 | 19 | ### Why is it called GhostBSD? 20 | 21 | GhostBSD was developed as an operating system to hack Gnome using FreeBSD technology. After a while, it became what was referred to as **(G)nome (host)ed by Free(BSD)**, which means that Gnome is hosted on the FreeBSD system. Today GhostBSD's name is still relevant to the past since MATE is a continuation of Gnome 2. 22 | 23 | ### On which FreeBSD branch is GhostBSD based? 24 | 25 | GhostBSD is based on the latest stable branch. It is currently on stable/14. 26 | 27 | ### Who can use GhostBSD? 28 | 29 | GhostBSD can be used by companies, researchers, data scientists, computer professionals, students, and home users worldwide in their work, education, and recreation. 30 | 31 | ### Does the GhostBSD license have any restrictions? 32 | 33 | Yes. Those restrictions do not control how you use the code, merely how you treat the GhostBSD Project. If you have serious license concerns, you can just read the actual license. For the simply curious, the license can be summarized like this: 34 | 35 | * Do not claim that you wrote this. 36 | * Do not sue us if it breaks. 37 | 38 | ### Can GhostBSD replace my current operating system? 39 | 40 | For most users, yes. 41 | 42 | Most people do not use an operating system. Instead, they use applications that make a computer useful. GhostBSD is designed to provide a desktop and full-featured environment for applications. It supports various web browsers, office suites, email readers, graphics programs, programming environments, network servers, and everything else you might want. Most of these applications can be built using the FreeBSD Ports Collection. 43 | 44 | If you need to use an application only available on a specific operating system, it may be hard to replace that operating system (this situation is called vendor lock-in). However, chances are that there is a very similar alternative application on GhostBSD. 45 | 46 | If you migrate to GhostBSD from some other UNIX®-like environment, you already know most of what you need to know. However, if your background is in graphic-driven operating systems such as Microsoft Windows® and older versions of MacOS®, expect to invest additional time learning the UNIX way of doing things. 47 | 48 | ## Support 49 | 50 | ### What’s the best way to get support? 51 | 52 | At this point, the best ways to contact other GhostBSD users or developers are: 53 | 54 | * On [Telegram](https://t.me/ghostbsd) you will meet developers and users 55 | * On [Element](https://app.element.io/#/room/#ghostbsd:matrix.org) which is connected with Telegram 56 | * On The [GhostBSD Forums](https://forums.ghostbsd.org) 57 | 58 | ## Software Installation 59 | 60 | ### How do I install new software? 61 | 62 | GhostBSD software can be installed in three different ways: 63 | 64 | * Software Station is the official UI tool to manage (search, install, and uninstall) binary packages on GhostBSD. 65 | * FreeBSD's package manager pkg can be used to manage. 66 | * Ports Tree can be used to install software from the ports package. 67 | 68 | ### Can I use Linux software on my GhostBSD system? 69 | 70 | First, you should know that most Linux software is open-source software. It is freely available for many operating systems, not just Linux. Therefore, most software that runs on Linux should also run on GhostBSD. 71 | 72 | Like FreeBSD, GhostBSD uses something called Linux Binary Compatibility. In a nutshell, that means you can run many Linux applications as-is. This **[section](https://docs.freebsd.org/en/books/handbook/linuxemu/)** of the FreeBSD Handbook explains this compatibility in more detail and describes when it does not work. 73 | 74 | However, you do not have to set up Linux Binary Compatibility on your GhostBSD system as it is already configured for you and should "just work". 75 | 76 | 77 | ## System and software updates 78 | 79 | ### How should I update GhostBSD to the latest updates? 80 | 81 | To upgrade GhostBSD, use the Update Station. It was made to upgrade GhostBSD properly. If you want the pkg command line, please follow this [article](upgrading-guide.md#ghostbsd-upgrade-with-pkg-cli). If you do not use pkg properly to upgrade GhostBSD, you will most likely get your system broken. 82 | 83 | ## Miscellaneous 84 | 85 | ### Why can't I compile code or ports on GhostBSD? 86 | 87 | GhostBSD no longer comes with development tools preinstalled. To enable the capability to compile code and ports, install the GhostBSD*-dev packages. These packages include essential build tools, compilers, and libraries necessary for software development. Use the following command to install them: 88 | 89 | ``` 90 | sudo pkg install -g 'GhostBSD*-dev' 91 | ``` 92 | -------------------------------------------------------------------------------- /contributor/getting-started/ghostbsd-contributors-guide.md: -------------------------------------------------------------------------------- 1 | GhostBSD Contributor's Guide 2 | ============================ 3 | 4 | ## 1. Introduction 5 | Welcome to the GhostBSD Contributor’s Guide. This guide outlines the responsibilities, workflows, and best practices for contributors, helping maintain the quality and consistency of the GhostBSD project. Being a committer allows you to directly contribute to the project’s growth and collaborate with a dedicated community. 6 | 7 | ## 2. Becoming An Official Contributor 8 | ### 2.1. Eligibility 9 | Anyone who has the interest to help the project can become a contributor. You must become a New Contributor first and have demonstrated a consistent track record of quality contributions to the GhostBSD project. 10 | ### 2.2. Mentorship Program 11 | New committers will be assigned a mentor by the project maintainers to guide them through the initial stages, ensuring they understand the project’s standards and workflows. 12 | ### 2.3. Trial Ending 13 | Once the mentor thinks the new contributor understands the project’s standards and workflows well the new contributor will become a contributor. 14 | 15 | ## 3. Contributor Responsibilities 16 | ### 3.1. Code Contributions 17 | Ensure your code contributions are well-tested and adhere to the project’s coding standards. 18 | ### 3.2. Code Reviews 19 | Participate in code reviews to help maintain code quality and mentor new contributors. 20 | ### 3.3. Documentation 21 | Update and improve documentation as part of your contributions. 22 | ### 3.4. Community Engagement 23 | Engage with the community by participating in discussions, answering questions, and providing support. 24 | 25 | ## 4. Using GitHub 26 | ### 4.1. Repository Structure 27 | Understand the structure of the GhostBSD repositories and where to find relevant code and documentation. 28 | ### 4.2. Branching Strategy 29 | Follow the project’s branching strategy for development, feature, and release branches: 30 | * **main**: Stable release branch. 31 | * **develop**: Ongoing development branch. 32 | * **feature/xxx**: Feature branches for new developments. 33 | ### 4.3. Cloning Repositories 34 | Clone the main repository: 35 | 36 | ``` 37 | git clone git@github.com:ghostbsd/ghostbsd.git 38 | ``` 39 | ### 4.4. Handling Merge Conflicts 40 | Resolve conflicts using Git: 41 | 42 | ``` 43 | git fetch origin 44 | git checkout feature/branch 45 | git merge origin/main 46 | # Resolve conflicts 47 | git add -A 48 | git commit 49 | ``` 50 | 51 | ## 5. Commit Messages 52 | ### 5.1. Format 53 | Use the following format for commit messages: 54 | 55 | ``` 56 | Subject Line (50 characters or less) 57 | 58 | Detailed explanation of the changes, reasons for the changes, and any additional 59 | information that might be useful. 60 | ``` 61 | ### 5.2. Best Practices 62 | * Use the imperative mood in the subject line (e.g., "Fix bug" not "Fixed bug"). 63 | * Include relevant issue numbers for traceability. 64 | ### 5.3. Examples 65 | * Good: Fix issue #123: Correct memory leak in network module 66 | * Bad: Fixed stuff 67 | 68 | ## 6. Working With Pull Requests 69 | ### 6.1. Creating a Pull Request 70 | Ensure your pull request is well-documented and includes relevant tests. 71 | ### 6.2. Reviewing Pull Requests 72 | Provide constructive feedback and ensure the code meets project standards. 73 | ### 6.3. Merging Pull Requests 74 | Merge pull requests only after they have been reviewed and approved by at least one other contributor. 75 | ### 6.4. Handling Complex Pull Requests 76 | * Breaking Down PRs: Divide large PRs into smaller, manageable parts. 77 | * Managing Dependencies: Ensure dependent PRs are noted and reviewed in order. 78 | 79 | ## 7. Code Reviews 80 | ### 7.1. Purpose 81 | Code reviews help maintain code quality and ensure adherence to project standards. 82 | ### 7.2. Process 83 | Review code for correctness, readability, and adherence to coding standards. Provide feedback and request changes if necessary. 84 | ### 7.3. Checklist 85 | * Compliance with coding standards. 86 | * Adequate test coverage. 87 | * Clear commit messages and documentation updates. 88 | 89 | ## 8. Handling Bug Reports 90 | ### 8.1. Triage 91 | Prioritize and categorize bug reports based on severity and impact. 92 | ### 8.2. Resolution 93 | Work on resolving bugs in a timely manner, ensuring that fixes are well-tested. 94 | ### 8.3. Examples 95 | * High Priority: Critical system crashes. 96 | * Medium Priority: Functionality issues. 97 | * Low Priority: Minor UI bugs. 98 | 99 | ## 9. Testing And Quality Assurance 100 | ### 9.1. Automated Testing 101 | Ensure your changes pass all relevant automated tests. 102 | ### 9.2. Manual Testing 103 | Perform manual testing when necessary, especially for user-facing features. 104 | ### 9.3. Continuous Integration 105 | Make use of the project’s continuous integration system to verify your changes. 106 | ### 9.4. Guidelines for Writing Tests 107 | * Use testing frameworks. 108 | * Include unit tests for new features. 109 | 110 | ## 10. Documentation 111 | ### 10.1. Updating Documentation 112 | Ensure that all changes are reflected in the relevant documentation. 113 | ### 10.2. Writing New Documentation 114 | Write clear, concise, and comprehensive documentation for new features and changes. 115 | ### 10.3. Standards 116 | * Use Markdown for documentation. 117 | * Follow the project’s style guide. 118 | ### 10.4. Tools 119 | * MkDocs for documentation management. 120 | 121 | ## 11. Communication 122 | ### 11.1. Communication Channels 123 | Use appropriate channels (mailing lists, forums, chat) for discussions and announcements. 124 | ### 11.2. Examples of Proper Etiquette 125 | * Respectful and constructive communication. 126 | * Professionalism in all interactions. 127 | 128 | ## 12. Resources 129 | ### 12.1. Documentation 130 | Access the project’s documentation portal for guidelines and references. 131 | ### 12.2. Tools 132 | Recommended tools and utilities for development: 133 | * IDEs: JetBrains IDEs, vscode, Sublime Text 134 | * Debugging Tools: GDB, LLDB -------------------------------------------------------------------------------- /contributor/getting-started/ghostbsd-contributors-guide-pl.md: -------------------------------------------------------------------------------- 1 | # Przewodnik dla Współpracowników GhostBSD 2 | 3 | ## 1. Wprowadzenie 4 | Witaj w Przewodniku dla Współpracowników GhostBSD. Ten przewodnik przedstawia obowiązki, przepływy pracy i najlepsze praktyki dla współpracowników, pomagając utrzymać jakość i spójność projektu GhostBSD. Bycie współpracownikiem pozwala bezpośrednio przyczynić się do rozwoju projektu i współpracować z oddaną społecznością. 5 | 6 | ## 2. Zostanie Oficjalnym Współpracownikiem 7 | ### 2.1. Kwalifikowalność 8 | Każdy, kto ma chęć pomocy projektowi, może zostać współpracownikiem. Najpierw musisz zostać Nowym Współpracownikiem i wykazać się spójnym śladem wysokiej jakości wkładu w projekt GhostBSD. 9 | ### 2.2. Program Mentorski 10 | Nowi współpracownicy zostaną przydzieleni mentorowi przez opiekunów projektu, który poprowadzi ich przez początkowe etapy, zapewniając zrozumienie standardów i przepływów pracy projektu. 11 | ### 2.3. Zakończenie Okresu Próbnego 12 | Gdy mentor uzna, że nowy współpracownik dobrze rozumie standardy i przepływy pracy projektu, nowy współpracownik zostanie oficjalnym współpracownikiem. 13 | 14 | ## 3. Obowiązki Współpracowników 15 | ### 3.1. Wkład w Kod 16 | Upewnij się, że Twoje wkłady kodu są dobrze przetestowane i przestrzegają standardów kodowania projektu. 17 | ### 3.2. Przeglądy Kodów 18 | Uczestnicz w przeglądach kodów, aby pomóc utrzymać jakość kodu i mentorować nowych współpracowników. 19 | ### 3.3. Dokumentacja 20 | Aktualizuj i poprawiaj dokumentację jako część swoich wkładów. 21 | ### 3.4. Angażowanie Społeczności 22 | Zaangażuj się w społeczność, uczestnicząc w dyskusjach, odpowiadając na pytania i udzielając wsparcia. 23 | 24 | ## 4. Używanie GitHub 25 | ### 4.1. Struktura Repozytoriów 26 | Zrozum strukturę repozytoriów GhostBSD i gdzie znaleźć odpowiedni kod i dokumentację. 27 | ### 4.2. Strategia Gałęzi 28 | Postępuj zgodnie ze strategią gałęzi projektu dla gałęzi rozwoju, funkcji i wydań: 29 | * **main**: Stabilna gałąź wydania. 30 | * **develop**: Gałąź bieżącego rozwoju. 31 | * **feature/xxx**: Gałęzie funkcji dla nowych rozwoju. 32 | ### 4.3. Klonowanie Repozytoriów 33 | Sklonuj główne repozytorium: 34 | 35 | ``` 36 | git clone git@github.com:ghostbsd/ghostbsd.git 37 | ``` 38 | ### 4.4. Rozwiązywanie Konfliktów Merge 39 | Rozwiązywanie konfliktów za pomocą Gita: 40 | 41 | ``` 42 | git fetch origin 43 | git checkout feature/branch 44 | git merge origin/main 45 | # Rozwiąż konflikty 46 | git add -A 47 | git commit 48 | ``` 49 | 50 | ## 5. Wiadomości o Commitach 51 | ### 5.1. Format 52 | Użyj następującego formatu dla wiadomości commitów: 53 | 54 | ``` 55 | Linia Tematu (50 znaków lub mniej) 56 | 57 | Szczegółowe wyjaśnienie zmian, powodów zmian i wszelkich dodatkowych informacji, które mogą być użyteczne. 58 | ``` 59 | ### 5.2. Najlepsze Praktyki 60 | * Używaj trybu rozkazującego w linii tematu (np. "Napraw błąd", a nie "Naprawiono błąd"). 61 | * Uwzględnij odpowiednie numery problemów dla śledzenia. 62 | ### 5.3. Przykłady 63 | * Dobrze: Naprawiono problem #123: Poprawa wycieku pamięci w module sieciowym 64 | * Źle: Naprawione rzeczy 65 | 66 | ## 6. Praca z Pull Requestami 67 | ### 6.1. Tworzenie Pull Requesta 68 | Upewnij się, że Twój pull request jest dobrze udokumentowany i zawiera odpowiednie testy. 69 | ### 6.2. Przeglądanie Pull Requestów 70 | Dostarczaj konstruktywną opinię i upewnij się, że kod spełnia standardy projektu. 71 | ### 6.3. Łączenie Pull Requestów 72 | Łącz pull requesty tylko po ich przeglądzie i zatwierdzeniu przez co najmniej jednego innego współpracownika. 73 | ### 6.4. Obsługa Złożonych Pull Requestów 74 | * Rozdzielanie PR: Podziel duże PR na mniejsze, zarządzalne części. 75 | * Zarządzanie Zależnościami: Upewnij się, że zależne PR są odnotowane i przeglądane w odpowiedniej kolejności. 76 | 77 | ## 7. Przeglądy Kodów 78 | ### 7.1. Cel 79 | Przeglądy kodów pomagają utrzymać jakość kodu i zapewniają przestrzeganie standardów projektu. 80 | ### 7.2. Proces 81 | Przeglądaj kod pod kątem poprawności, czytelności i przestrzegania standardów kodowania. Przekazuj opinie i żądaj zmian, jeśli to konieczne. 82 | ### 7.3. Lista Kontrolna 83 | * Zgodność ze standardami kodowania. 84 | * Odpowiednia pokrycie testów. 85 | * Jasne wiadomości commitów i aktualizacje dokumentacji. 86 | 87 | ## 8. Obsługa Zgłoszeń Błędów 88 | ### 8.1. Selekcja 89 | Priorytetyzuj i klasyfikuj zgłoszenia błędów na podstawie ich powagi i wpływu. 90 | ### 8.2. Rozwiązywanie 91 | Pracuj nad rozwiązywaniem błędów w odpowiednim czasie, zapewniając, że poprawki są dobrze przetestowane. 92 | ### 8.3. Przykłady 93 | * Wysoki Priorytet: Krytyczne awarie systemu. 94 | * Średni Priorytet: Problemy z funkcjonalnością. 95 | * Niski Priorytet: Drobne błędy UI. 96 | 97 | ## 9. Testowanie i Zapewnienie Jakości 98 | ### 9.1. Testy Automatyczne 99 | Upewnij się, że Twoje zmiany przechodzą wszystkie odpowiednie testy automatyczne. 100 | ### 9.2. Testy Ręczne 101 | Przeprowadzaj testy ręczne, gdy jest to konieczne, zwłaszcza dla funkcji związanych z interfejsem użytkownika. 102 | ### 9.3. Integracja Ciągła 103 | Korzystaj z systemu integracji ciągłej projektu, aby zweryfikować swoje zmiany. 104 | ### 9.4. Wytyczne dotyczące Pisania Testów 105 | * Używaj frameworków testowych. 106 | * Uwzględniaj testy jednostkowe dla nowych funkcji. 107 | 108 | ## 10. Dokumentacja 109 | ### 10.1. Aktualizacja Dokumentacji 110 | Upewnij się, że wszystkie zmiany są odzwierciedlone w odpowiedniej dokumentacji. 111 | ### 10.2. Pisanie Nowej Dokumentacji 112 | Pisanie jasnej, zwięzłej i kompleksowej dokumentacji dla nowych funkcji i zmian. 113 | ### 10.3. Standardy 114 | * Używaj Markdown do dokumentacji. 115 | * Przestrzegaj przewodnika stylu projektu. 116 | ### 10.4. Narzędzia 117 | * MkDocs do zarządzania dokumentacją. 118 | 119 | ## 11. Komunikacja i Zachowanie 120 | ### 11.1. Kodeks Postępowania 121 | Przestrzegaj kodeksu postępowania projektu we wszystkich interakcjach. 122 | ### 11.2. Kanały Komunikacji 123 | Używaj odpowiednich kanałów (listy mailingowe, fora, czat) do dyskusji i ogłoszeń. 124 | ### 11.3. Przykłady Odpowiedniego Zachowania 125 | * Szacunek i konstruktywna komunikacja. 126 | * Profesjonalizm we wszystkich interakcjach. 127 | 128 | ## 12. Zasoby 129 | ### 12.1. Dokumentacja 130 | Dostęp do portalu dokumentacji projektu dla wytycznych i odniesień. 131 | ### 12.2. Narzędzia 132 | Rekomendowane narzędzia i urządzenia dla rozwoju: 133 | * IDE: JetBrains IDEs, vscode, Sublime Text 134 | * Narzędzia Debuggingowe: GDB, LLDB -------------------------------------------------------------------------------- /user/security-key.md: -------------------------------------------------------------------------------- 1 | # Security Key configuration Guide 2 | 3 | This document aims to cover the setup and configuration of security keys on GhostBSD. Security keys like YubiKey provide multiple authentication methods and security features that can be used for web authentication, system login, SSH access, and more. 4 | 5 | ```{contents} Table of Contents 6 | :depth: 3 7 | :local: 8 | ``` 9 | 10 | ## FIDO2/WebAuthn Security Key Setup 11 | 12 | This section will help you set up FIDO2/WebAuthn security keys (like YubiKeys) on GhostBSD. Security keys provide strong two-factor authentication for websites and services that support WebAuthn. 13 | 14 | ### What You'll Need 15 | 16 | - A FIDO2/WebAuthn compatible security key (YubiKey, etc.) 17 | - Administrator (root) access on your GhostBSD system 18 | - A web browser (Firefox or Chromium) 19 | 20 | ### Step 1: Install Required Packages 21 | 22 | Open a terminal and install the necessary packages: 23 | 24 | ```bash 25 | sudo pkg install libu2f-host libfido2 u2f-devd 26 | ``` 27 | 28 | These packages provide: 29 | - `libu2f-host`: Library for communicating with U2F/FIDO devices 30 | - `libfido2`: Modern FIDO2/WebAuthn library and tools 31 | - `u2f-devd`: Device management for security keys 32 | 33 | ### Step 2: Configure USB HID Support 34 | 35 | #### Load USB HID Module 36 | 37 | Add the USB HID module to your system's kernel module list: 38 | 39 | ```bash 40 | sudo sysrc kld_list+="usbhid" 41 | ``` 42 | 43 | This command safely adds `usbhid` to the existing `kld_list` without overwriting other modules. 44 | 45 | #### Disable Legacy USB HID 46 | 47 | Edit the boot loader configuration: 48 | 49 | ```bash 50 | sudo ee /boot/loader.conf 51 | ``` 52 | 53 | Add this line: 54 | 55 | ``` 56 | hw.usb.usbhid.enable="0" 57 | ``` 58 | 59 | This disables the legacy USB HID system in favor of the newer one. 60 | 61 | ### Step 3: Set Up User Permissions 62 | 63 | Add your user account to the `u2f` group: 64 | 65 | ```bash 66 | sudo pw group mod u2f -m yourusername 67 | ``` 68 | 69 | Replace `yourusername` with your actual username. 70 | 71 | **Important:** You must reboot after making these changes for them to take effect. 72 | 73 | ### Step 4: Reboot Your System 74 | 75 | ```bash 76 | sudo reboot 77 | ``` 78 | 79 | ### Step 5: Test Your Security Key 80 | 81 | After rebooting, plug in your security key and test it: 82 | 83 | #### Find Your Security Key 84 | 85 | ```bash 86 | fido2-token -L 87 | ``` 88 | 89 | You should see output like: 90 | ``` 91 | /dev/uhid3: vendor=0x1050, product=0x0407 (Yubico YubiKey OTP+FIDO+CCID) 92 | ``` 93 | 94 | #### Check Device Information 95 | 96 | ```bash 97 | fido2-token -I /dev/uhid3 98 | ``` 99 | 100 | Replace `/dev/uhid3` with whatever device path was shown in the previous command. 101 | 102 | ### Step 6: Configure Your Browser 103 | 104 | #### Firefox Configuration 105 | 106 | 1. Open Firefox 107 | 2. Type `about:config` in the address bar and press Enter 108 | 3. Click "Accept the Risk and Continue" 109 | 4. Search for each setting and change the values: 110 | 111 | | Setting | Value | 112 | |---------|-------| 113 | | `security.webauth.u2f` | `true` | 114 | | `security.webauth.webauthn` | `true` | 115 | | `security.webauth.webauthn_enable_softtoken` | `true` | 116 | | `security.webauth.webauthn_enable_usbtoken` | `true` | 117 | 118 | 5. Restart Firefox 119 | 120 | #### Chromium Configuration 121 | 122 | Chromium usually works with security keys without additional configuration on GhostBSD. 123 | 124 | ### Step 7: Test WebAuthn 125 | 126 | 1. Go to [WebAuthn.io](https://webauthn.io) in your browser 127 | 2. Click "Register" to test registration 128 | 3. Enter your security key PIN when prompted 129 | 4. Touch your security key when the browser requests it 130 | 5. Try "Authenticate" to test login 131 | 132 | ### Troubleshooting 133 | 134 | #### Security Key Not Detected 135 | 136 | If `fido2-token -L` doesn't show your key: 137 | 138 | 1. Try unplugging and reinserting the security key. 139 | 140 | 2. Check if you're in the correct groups: 141 | ```bash 142 | groups 143 | ``` 144 | You should see `u2f` and `operator` in the output. 145 | 146 | 3. Check device permissions: 147 | ```bash 148 | ls -la /dev/uhid* 149 | ``` 150 | Look for a device with group `u2f` or different permissions. 151 | 152 | #### PIN Locked Error 153 | 154 | If you see "security key is locked" or "wrong pin entered too many times": 155 | 156 | 1. Check PIN status: 157 | ```bash 158 | fido2-token -I /dev/uhid3 159 | ``` 160 | Look for `pin retries: 0` in the output. 161 | 162 | 2. If PIN retries is 0, you need to reset the FIDO2 application: 163 | ```bash 164 | fido2-token -R /dev/uhid3 165 | ``` 166 | **Warning:** This deletes all FIDO2 credentials on the key! 167 | 168 | 3. When the command runs, immediately touch and hold your security key for 3-5 seconds to confirm the reset. 169 | 170 | 4. Set a new PIN: 171 | ```bash 172 | fido2-token -S /dev/uhid3 173 | ``` 174 | Enter your new PIN twice when prompted. 175 | 176 | #### Browser Issues 177 | 178 | **Firefox doesn't work but Chromium does:** 179 | - Double-check the `about:config` settings 180 | - Try restarting Firefox completely 181 | - Clear Firefox cache and cookies for the website 182 | - Try in a private/incognito window 183 | 184 | **Neither browser works:** 185 | - Verify your user is in the `u2f` group: `groups` 186 | - Try with a different USB port 187 | 188 | ### Setting Up a PIN (Recommended) 189 | 190 | For security, set up a PIN on your security key: 191 | 192 | ```bash 193 | fido2-token -S /dev/uhid3 194 | ``` 195 | 196 | Choose a PIN that's at least 4 characters long. You'll need to enter this PIN when using the key for authentication. 197 | 198 | ### What's Next? 199 | 200 | With your security key working, you can now: 201 | 202 | - Enable two-factor authentication on websites that support WebAuthn/FIDO2 203 | - Use SSH authentication with FIDO2 keys 204 | - Set up system login with security keys (advanced) 205 | 206 | ### Common Commands Reference 207 | 208 | | Command | Purpose | 209 | |---------|---------| 210 | | `fido2-token -L` | List available FIDO2 devices | 211 | | `fido2-token -I /dev/uhidX` | Show device information | 212 | | `fido2-token -S /dev/uhidX` | Set initial PIN | 213 | | `fido2-token -C /dev/uhidX` | Change existing PIN | 214 | | `fido2-token -R /dev/uhidX` | Reset FIDO2 application (deletes credentials) | 215 | | `fido2-cred -L /dev/uhidX` | List stored credentials | 216 | 217 | Remember to replace `/dev/uhidX` with your actual device path (usually `/dev/uhid3` for security keys). 218 | 219 | ### Security Notes 220 | 221 | - Always set a PIN on your security key for additional security 222 | - Keep backup authentication methods enabled on important accounts 223 | - The reset command (`fido2-token -R`) permanently deletes all FIDO2 credentials 224 | - Other functions on multi-purpose keys (like YubiKey OTP) are not affected by FIDO2 reset 225 | 226 | --- 227 | 228 | **Need more help?** Visit the [GhostBSD Forums](https://forums.ghostbsd.org) for community support. -------------------------------------------------------------------------------- /user/installation-guide/full-disk-installation.md: -------------------------------------------------------------------------------- 1 | Full disk installation 2 | ====================== 3 | 4 | ## Starting the GhostBSD live system 5 | 6 | Insert the GhostBSD flash drive and reboot or turn on the computer. Before the computer boots an existing OS it is necessary to select the flash drive as the boot device. This can be done by: 7 | 8 | * Entering the computer's BIOS or UEFI interface and selecting the flash drive. 9 | * Pressing a designated key to choose the boot device and selecting the flash drive. 10 | 11 | The keys to enter the BIOS or UEFI interface or select boot devices vary between motherboards. The proper key may be displayed during the boot process and is often *Del*, *Esc*, or *F1* through *F12*. 12 | 13 | If the computer boots into an existing OS, it may mean: 14 | 15 | * The flash drive was not properly inserted. 16 | * The BIOS or UEFI changes were not saved. 17 | * The computer does not support booting from the desired device. 18 | * The proper key was not pressed, or pressed at the correct time, during the boot process. 19 | * There was an error while creating the live flash drive. 20 | 21 | As GhostBSD boots, the loader menu will appear and will look similar to one of the images below depending if the system is booted in UEFI or BIOS mode. 22 | 23 | ![Loader menu for GhostBSD booted in UEFI mode.](images/full-disk-installation/0-boot-uefi.png) 24 | 25 | ![Loader menu for GhostBSD booted in BIOS mode.](images/full-disk-installation/0-boot-bios.png) 26 | 27 | GhostBSD will finish booting and will automatically load the Mate desktop environment. 28 | 29 | ![Mate desktop environment of GhostBSD live system.](images/full-disk-installation/1-desktop.png) 30 | 31 | ## Using the live system 32 | 33 | It is possible to use this live system to test hardware compatibility or to become familiar with basic GhostBSD features and default software. 34 | 35 | ## Installing GhostBSD 36 | 37 | ### Starting the installer 38 | 39 | Double click the "Install GhostBSD" desktop icon to start the installer. A new window will appear with the following screens to setup and install a GhostBSD system. To save changes and proceed through the installation, click "Next". You may click "Previous" to return to the previous screen and make additional changes. Click "Cancel" or the red circle (top right corner) to exit the installer. 40 | 41 | ### Localization 42 | 43 | #### Language 44 | 45 | Select the language you would like to use for your installed system. If you need to change the system language after installation, more information about localization can be found in the [FreeBSD Handbook](https://docs.freebsd.org/en/books/handbook/l10n/). 46 | 47 | ![Language selection in GhostBSD installer.](images/full-disk-installation/2-localization-language.png) 48 | 49 | **Please note**: Currently, the installer only supports English during the installation process. 50 | 51 | #### Keyboard 52 | 53 | You may select a keyboard layout specific to your language or region. It is also possible to specify the model of keyboard. If you do not know the model of your keyboard, or it is not listed, you should simply click "Next" without making a selection. 54 | 55 | ![Keyboard selection in GhostBSD installer.](images/full-disk-installation/3-localization-keyboard.png) 56 | 57 | #### Time zone 58 | 59 | Select your time zone to allow the system to adjust to regional time changes and properly perform other time zone related functions. 60 | 61 | ![Timezone selection in GhostBSD installer.](images/full-disk-installation/4-localization-timezone.png) 62 | 63 | ### Disks and filesystem 64 | 65 | #### Installation type 66 | 67 | Select *Full disk configuration* to install GhostBSD with the default ZFS configuration. It is possible to use other filesystems and partitioning schemes by selecting *Custom (Advanced partitioning)*. 68 | 69 | ![Installation type selection in GhostBSD installer.](images/full-disk-installation/5-install-type.png) 70 | 71 | #### Installation disk 72 | 73 | Select the disk where GhostBSD should be installed by clicking the corresponding checkbox. There are additional ZFS options that may be changed from this screen. However, the default values are generally appropriate for most users and systems. 74 | 75 | ![Installation location selection in GhostBSD installer.](images/full-disk-installation/6-install-location.png) 76 | 77 | **Please note**: The selected disk will be formatted during the installation and any existing data will be lost. 78 | 79 | ### Boot loader 80 | 81 | By default, GhostBSD uses the native FreeBSD boot loader. If you plan to use multiple operating systems from a single machine, it may be convenient to choose rEFInd rather than the default. rEFInd can detect other operating systems and chainload their respective, native boot loaders. This can remove the need to override the boot device as described previously in [Booting from the GhostBSD flash drive](#booting-from-the-ghostbsd-flash-drive). 82 | 83 | ![Boot loader selection in GhostBSD installer.](images/full-disk-installation/7-loader-uefi.png) 84 | 85 | **Please note**: If the live system was booted in UEFI mode, the installer will show "FreeBSD *UEFI* loader only". If booted in BIOS mode, the installer will show "FreeBSD *BIOS* loader only". 86 | 87 | ### Root password 88 | 89 | Unix-like operating systems have an administrative user called root. Root has the ability to make any change to the system or users. Therefore, it is necessary to create a strong password for root. Any password can be used but the installer will suggest if it is weak or strong. 90 | 91 | ![Root password creation in GhostBSD installer.](images/full-disk-installation/8-accounts-root.png) 92 | 93 | ### Adding a user 94 | 95 | Create your user by entering a *Real name*, *User name*, and *Password*. The installer will again suggest whether the password is weak or strong. The *Hostname* is the name of your computer that is displayed on any networks. It will be automatically created but can be changed if desired. The *Shell* is what you interact with when using the terminal (command line). GhostBSD aims provides a user-friendly GUI experience and it is not often required to use the terminal. The default shell is fish, however, several others are included. 96 | ![User creation in GhostBSD installer.](images/full-disk-installation/9-accounts-user.png) ### Finish and reboot #### Progress screen 97 | After a user is created, click "Install" to complete the installation. A progress screen will appear that shows the actions being performed and other messages. 98 | 99 | ![Progress screen in GhostBSD installer.](images/full-disk-installation/10-progress.png) 100 | 101 | #### Reboot into new installation 102 | 103 | If the installation is successful, the below screen will be displayed. Click "Continue" to remain in the live system or click "Restart" to reboot into the newly installed GhostBSD system. Be sure remove the flash drive after the computer shuts down but before it restarts. Some machines may automatically boot from an attached live flash drive. 104 | 105 | ![Finish and restart screen in GhostBSD installer.](images/full-disk-installation/11-complete.png) 106 | -------------------------------------------------------------------------------- /user/installation-guide/full-disk-installation-pl.md: -------------------------------------------------------------------------------- 1 | Pełna instalacja na dysku 2 | ====================== 3 | 4 | ## Rozpoczęcie pracy z systemem GhostBSD live 5 | 6 | Włóż pamięć USB z GhostBSD i uruchom ponownie lub włącz komputer. Przed uruchomieniem istniejącego systemu operacyjnego konieczne jest wybranie pamięci USB jako urządzenia startowego. Można to zrobić przez: 7 | 8 | * Wejście do interfejsu BIOS lub UEFI komputera i wybranie pamięci USB. 9 | * Naciśnięcie odpowiedniego klawisza, aby wybrać urządzenie startowe, i wybranie pamięci USB. 10 | 11 | Klawisze do wejścia do BIOS lub UEFI lub wyboru urządzeń startowych różnią się między płytami głównymi. Odpowiedni klawisz może być wyświetlony podczas procesu uruchamiania i często jest to *Del*, *Esc*, lub *F1* albo *F12*. 12 | 13 | Jeśli komputer uruchomi istniejący system operacyjny, może to oznaczać: 14 | 15 | * Pamięć USB nie została prawidłowo włożona. 16 | * Zmiany w BIOS lub UEFI nie zostały zapisane. 17 | * Komputer nie obsługuje uruchamiania z wybranego urządzenia. 18 | * Odpowiedni klawisz nie został naciśnięty lub naciśnięty we właściwym czasie podczas procesu uruchamiania. 19 | * Wystąpił błąd podczas tworzenia dysku USB live. 20 | 21 | Podczas uruchamiania GhostBSD pojawi się menu ładujące, które będzie wyglądać podobnie do jednego z poniższych obrazów, w zależności od tego, czy system jest uruchomiony w trybie UEFI, czy BIOS. 22 | 23 | ![Menu ładujące dla GhostBSD uruchomione w trybie UEFI.](images/full-disk-installation/0-boot-uefi.png) 24 | 25 | ![Menu ładujące dla GhostBSD uruchomione w trybie BIOS.](images/full-disk-installation/0-boot-bios.png) 26 | 27 | GhostBSD zakończy uruchamianie i automatycznie załaduje środowisko desktopowe Mate. 28 | 29 | ![Środowisko desktopowe Mate systemu GhostBSD live.](images/full-disk-installation/1-desktop.png) 30 | 31 | ## Korzystanie z systemu live 32 | 33 | Możliwe jest użycie tego systemu live do testowania kompatybilności sprzętu lub zapoznania się z podstawowymi funkcjami GhostBSD i domyślnym oprogramowaniem. 34 | 35 | ## Instalacja GhostBSD 36 | 37 | ### Rozpoczęcie instalatora 38 | 39 | Kliknij dwukrotnie ikonę "Install GhostBSD" na pulpicie, aby uruchomić instalator. Pojawi się nowe okno z następującymi ekranami, aby skonfigurować i zainstalować system GhostBSD. Aby zapisać zmiany i przejść dalej, kliknij "Next". Możesz kliknąć "Previous", aby wrócić do poprzedniego ekranu i dokonać dodatkowych zmian. Kliknij "Cancel" lub czerwony okrąg (w prawym górnym rogu), aby wyjść z instalatora. 40 | 41 | ### Lokalizacja 42 | 43 | #### Język 44 | 45 | Wybierz język, którego chcesz używać w zainstalowanym systemie. Jeśli chcesz zmienić język systemu po instalacji, więcej informacji na temat lokalizacji znajdziesz w [Podręczniku FreeBSD](https://docs.freebsd.org/en/books/handbook/l10n/). 46 | 47 | ![Wybór języka w instalatorze GhostBSD.](images/full-disk-installation/2-localization-language.png) 48 | 49 | **Uwaga**: Obecnie instalator obsługuje tylko język angielski podczas procesu instalacji. 50 | 51 | #### Klawiatura 52 | 53 | Możesz wybrać układ klawiatury specyficzny dla twojego języka lub regionu. Można również określić model klawiatury. Jeśli nie znasz modelu swojej klawiatury lub nie jest ona wymieniona, powinieneś po prostu kliknąć "Next" bez dokonywania wyboru. 54 | 55 | ![Wybór klawiatury w instalatorze GhostBSD.](images/full-disk-installation/3-localization-keyboard.png) 56 | 57 | #### Strefa czasowa 58 | 59 | Wybierz swoją strefę czasową, aby system mógł dostosować się do regionalnych zmian czasu i prawidłowo wykonywać inne funkcje związane ze strefą czasową. 60 | 61 | ![Wybór strefy czasowej w instalatorze GhostBSD.](images/full-disk-installation/4-localization-timezone.png) 62 | 63 | ### Dyski i system plików 64 | 65 | #### Rodzaj instalacji 66 | 67 | Wybierz *Konfiguracja pełnego dysku*, aby zainstalować GhostBSD z domyślną konfiguracją ZFS. Możliwe jest użycie innych systemów plików i schematów partycjonowania, wybierając *Niestandardowe (Zaawansowane partycjonowanie)*. 68 | 69 | ![Wybór rodzaju instalacji w instalatorze GhostBSD.](images/full-disk-installation/5-install-type.png) 70 | 71 | #### Dysk instalacyjny 72 | 73 | Wybierz dysk, na którym ma zostać zainstalowany GhostBSD, klikając odpowiednie pole wyboru. Na tym ekranie można również zmienić dodatkowe opcje ZFS. Jednak domyślne wartości są zazwyczaj odpowiednie dla większości użytkowników i systemów. 74 | 75 | ![Wybór lokalizacji instalacji w instalatorze GhostBSD.](images/full-disk-installation/6-install-location.png) 76 | 77 | **Uwaga**: Wybrany dysk zostanie sformatowany podczas instalacji i wszelkie istniejące dane zostaną utracone. 78 | 79 | ### Boot loader 80 | 81 | Domyślnie GhostBSD używa natywnego boot loadera FreeBSD. Jeśli planujesz używać wielu systemów operacyjnych na jednym komputerze, może być wygodniej wybrać rEFInd zamiast domyślnego. rEFInd potrafi wykryć inne systemy operacyjne i uruchamiać ich natywne boot loadery. Może to wyeliminować konieczność zmiany urządzenia startowego, jak opisano wcześniej w [Uruchamianie z pamięci USB GhostBSD](#booting-from-the-ghostbsd-flash-drive). 82 | 83 | ![Wybór boot loadera w instalatorze GhostBSD.](images/full-disk-installation/7-loader-uefi.png) 84 | 85 | **Uwaga**: Jeśli system live został uruchomiony w trybie UEFI, instalator pokaże "FreeBSD *UEFI* loader only". Jeśli uruchomiono w trybie BIOS, instalator pokaże "FreeBSD *BIOS* loader only". 86 | 87 | ### Hasło root 88 | 89 | Systemy operacyjne typu Unix mają użytkownika administracyjnego o nazwie root. Root ma możliwość wprowadzania dowolnych zmian w systemie lub użytkownikach. Dlatego konieczne jest utworzenie silnego hasła dla roota. Można użyć dowolnego hasła, ale instalator zasugeruje, czy jest ono słabe, czy silne. 90 | 91 | ![Tworzenie hasła root w instalatorze GhostBSD.](images/full-disk-installation/8-accounts-root.png) 92 | 93 | ### Dodawanie użytkownika 94 | 95 | Utwórz użytkownika, wprowadzając *Prawdziwe imię*, *Nazwa użytkownika* i *Hasło*. Instalator ponownie zasugeruje, czy hasło jest słabe, czy silne. *Hostname* to nazwa twojego komputera wyświetlana w sieciach. Zostanie ona automatycznie utworzona, ale można ją zmienić, jeśli jest taka potrzeba. *Shell* to to, z czym będziesz wchodzić w interakcję podczas korzystania z terminala (wiersza poleceń). GhostBSD stara się zapewnić przyjazne dla użytkownika doświadczenie GUI i rzadko wymaga korzystania z terminala. Domyślną powłoką jest fish, jednak dostępnych jest kilka innych. 96 | 97 | ![Tworzenie użytkownika w instalatorze GhostBSD.](images/full-disk-installation/9-accounts-user.png) 98 | 99 | ### Zakończenie i ponowne uruchomienie 100 | 101 | #### Ekran postępu 102 | 103 | Po utworzeniu użytkownika kliknij "Install", aby zakończyć instalację. Pojawi się ekran postępu, który pokazuje wykonywane działania i inne komunikaty. 104 | 105 | ![Ekran postępu w instalatorze GhostBSD.](images/full-disk-installation/10-progress.png) 106 | 107 | #### Ponowne uruchomienie do nowej instalacji 108 | 109 | Jeśli instalacja zakończy się pomyślnie, pojawi się poniższy ekran. Kliknij "Continue", aby pozostać w systemie live, lub kliknij "Restart", aby ponownie uruchomić system GhostBSD. Upewnij się, że usuniesz pamięć USB po wyłączeniu komputera, ale przed jego ponownym uruchomieniem. Niektóre maszyny mogą automatycznie uruchamiać się z podłączonej pamięci USB live. 110 | 111 | ![Zakończenie i ponowne uruchomienie w instalatorze GhostBSD.](images/full-disk-installation/11-complete.png) -------------------------------------------------------------------------------- /contributor/maintenance-release/package-process.md: -------------------------------------------------------------------------------- 1 | # Package Management Process 2 | 3 | GhostBSD operates a three-tier package repository system that delivers stable packages to users while supporting continuous development and thorough testing. 4 | 5 | ## Repository Structure 6 | 7 | GhostBSD maintains three distinct package repositories: 8 | 9 | ### Unstable Repository 10 | - **Purpose**: Developer playground and experimental builds 11 | - **Target Users**: Developers working on new features and ports 12 | - **FreeBSD Base**: Tracks the next FreeBSD releng development branch (e.g., releng/15.0 when created) 13 | - **Update Frequency**: Independent development builds 14 | - **Risk Level**: High - experimental features and bleeding-edge development 15 | - **Isolation**: Operates independently from testing and stable repositories 16 | 17 | ### Testing Repository 18 | - **Purpose**: Pre-production testing environment (what "unstable" was previously) 19 | - **Target Users**: Contributors and community members who help test packages 20 | - **FreeBSD Base**: Current stable FreeBSD release (e.g., 14.3-RELEASE) 21 | - **Update Frequency**: Regular builds awaiting validation before user deployment 22 | - **Risk Level**: Medium - packages undergo testing before reaching users 23 | 24 | ### Stable Repository 25 | - **Purpose**: Production packages for end users 26 | - **Target Users**: All GhostBSD users 27 | - **FreeBSD Base**: Current stable FreeBSD release 28 | - **Update Frequency**: Synchronized from testing after validation 29 | - **Risk Level**: Low - fully tested and validated packages 30 | 31 | ## Package Flow 32 | 33 | ``` 34 | [Unstable] [Testing] → [Stable] 35 | ↓ ↓ ↓ 36 | Development Community Production 37 | (Independent) Testing 38 | ``` 39 | 40 | ### How Packages Move 41 | 42 | 1. **Unstable Repository (Independent Development)** 43 | - Developers build and test experimental features 44 | - Tracks the next FreeBSD releng development branch for early compatibility testing 45 | - Packages do not automatically flow to testing or stable 46 | - Provides early feedback on upcoming FreeBSD version compatibility 47 | 48 | 2. **Testing to Stable Flow** 49 | - Testing serves as the validation environment before user deployment 50 | - Packages undergo builds and testing in the testing repository 51 | - Only after thorough testing are packages synchronized to stable 52 | - Same repository build with testing gates before promotion to stable 53 | 54 | ## Package Repository Configuration 55 | 56 | #### Stable (Default for Users) 57 | ``` 58 | GhostBSD: { 59 | url: "https://pkg.ghostbsd.org/stable/${ABI}/latest", 60 | signature_type: "pubkey", 61 | pubkey: "/usr/share/keys/ssl/certs/ghostbsd.cert", 62 | enabled: yes 63 | } 64 | 65 | GhostBSD-base: { 66 | url: "https://pkg.ghostbsd.org/stable/${ABI}/base", 67 | signature_type: "pubkey", 68 | pubkey: "/usr/share/keys/ssl/certs/ghostbsd.cert", 69 | enabled: yes 70 | } 71 | ``` 72 | 73 | #### Testing (For Contributors and Community Testers) 74 | ``` 75 | GhostBSD: { 76 | url: "https://pkg.ghostbsd.org/testing/${ABI}/latest", 77 | signature_type: "pubkey", 78 | pubkey: "/usr/share/keys/ssl/certs/ghostbsd.cert", 79 | enabled: yes 80 | } 81 | 82 | GhostBSD-base: { 83 | url: "https://pkg.ghostbsd.org/testing/${ABI}/base", 84 | signature_type: "pubkey", 85 | pubkey: "/usr/share/keys/ssl/certs/ghostbsd.cert", 86 | enabled: yes 87 | } 88 | ``` 89 | 90 | #### Unstable (For Developers) 91 | ``` 92 | GhostBSD: { 93 | url: "https://pkg.ghostbsd.org/unstable/${ABI}/latest", 94 | signature_type: "pubkey", 95 | pubkey: "/usr/share/keys/ssl/certs/ghostbsd.cert", 96 | enabled: yes 97 | } 98 | 99 | GhostBSD-base: { 100 | url: "https://pkg.ghostbsd.org/unstable/${ABI}/base", 101 | signature_type: "pubkey", 102 | pubkey: "/usr/share/keys/ssl/certs/ghostbsd.cert", 103 | enabled: yes 104 | } 105 | ``` 106 | 107 | ## System Benefits 108 | 109 | ### For Developers 110 | - **Sandbox Environment**: Unstable provides an isolated development environment 111 | - **Early FreeBSD Testing**: Developers test against the next FreeBSD releng development branch 112 | - **No User Impact**: Development work does not affect testing or production users 113 | 114 | ### For Contributors and Community Testers 115 | - **Focused Validation**: Testing repository focuses on pre-production validation 116 | - **Stable Base**: Built on stable FreeBSD releases for consistent testing environments 117 | - **Clear Gateway**: Serves as the final validation gate before user deployment 118 | 119 | ### For Users 120 | - **Proven Stability**: Packages reach users only after community testing validation 121 | - **Reliable Updates**: Community testing ensures package quality before deployment 122 | - **Consistent Experience**: Built on stable FreeBSD releases 123 | 124 | ## Repository Operations 125 | 126 | ### FreeBSD Release Alignment 127 | 128 | When FreeBSD creates a new releng development branch (e.g., `releng/15.0`): 129 | 130 | 1. **Unstable** switches to track the next FreeBSD releng development branch 131 | 2. **Testing** continues operating with current stable FreeBSD (14.3-RELEASE) 132 | 3. **Stable** remains synchronized with testing 133 | 134 | This operational model: 135 | - Detects FreeBSD compatibility issues early in unstable 136 | - Provides extended testing periods for major FreeBSD updates 137 | - Ensures smooth transitions for end users via the testing→stable flow 138 | 139 | ### Development Operations 140 | 141 | #### Experimental Development 142 | - Developers operate in the unstable repository for experimental work 143 | - Features are developed and tested against the next FreeBSD releng development branch 144 | - No automatic promotion to testing occurs - requires deliberate decisions 145 | 146 | #### Production Pipeline 147 | 1. Packages are built in testing repository 148 | 2. Community validation and testing procedures are applied 149 | 3. Successful packages are synchronized to stable for users 150 | 151 | #### Security Updates (CVEs) 152 | 1. Security updates are built and tested in testing repository 153 | 2. Expedited community validation processes are applied 154 | 3. Quick synchronization to stable for security patches 155 | 156 | ## System Implementation 157 | 158 | ### Build Infrastructure 159 | - Independent build environment for unstable (next FreeBSD releng development branch) 160 | - Shared build infrastructure for testing/stable (same repository with different promotion stages) 161 | - Automated synchronization mechanisms from testing to stable 162 | 163 | ### Testing Procedures 164 | - Community testing in testing repository before stable promotion 165 | - Validation gates before synchronization to stable 166 | - Community-driven validation processes 167 | 168 | ### User Communication 169 | - Documentation of repository purposes 170 | - Guidelines for developers on unstable usage 171 | - Release notes for testing→stable promotions 172 | 173 | ## Historical Context 174 | 175 | GhostBSD's three-tier system addresses challenges from previous approaches: 176 | 177 | - **Previous Two-Tier System**: Unstable served dual purposes of development and pre-production testing 178 | - **Developer Isolation**: Developers now operate in an experimental environment without affecting the user pipeline 179 | - **Testing Clarity**: Testing repository now operates as a focused pre-production environment 180 | 181 | This system separates development experimentation from the user-focused testing→stable pipeline while giving developers early access to the next FreeBSD releng development branches. -------------------------------------------------------------------------------- /user/installation-guide/custom-installation.md: -------------------------------------------------------------------------------- 1 | Custom Installation 2 | =================== 3 | 4 | A custom installation and full disk installation of GhostBSD begin the same way. Please follow the [Full disk installation](full-disk-installation.md) guide until the *Disks and filesystem* section. When that section is reached, follow this guide to complete the custom installation. 5 | 6 | The purpose of this guide is not to provide the steps for every possible configuration, but to provide some background to help with custom partitioning and filesystem layouts. The [Installing GhostBSD](#installing-ghostbsd) section has the steps needed for a custom installation with the recommended setup using UEFI, GPT and OpenZFS. 7 | 8 | ## Partitioning schemes 9 | 10 | There are two partitioning schemes available in GhostBSD that are used to divide a disk into sections called slices or partitions. There is the Master Boot Record (MBR) layout and the GUID Partition Table (GPT) layout. Generally, MBR disks are used if the machine boots with the legacy Basic Input/Output System (BIOS) and GPT disks are used when booting with the newer Unified Extensible Firmware Interface (UEFI). UEFI can boot from a GPT or MBR disk and in some machines there is compatibility code that allows BIOS to boot from GPT disks, in addition to, MBR disks.[^1] 11 | 12 | ### MBR 13 | 14 | There are several limitations when using the older MBR layout including limits on the size of the disk and number of partitions that are possible. MBR only officially supports disks that are up to two terabytes. There is also a limit of four primary partitions but an extended partition may be used to increase this number.[^2] 15 | 16 | ### GPT 17 | 18 | GPT is a newer partitioning scheme created by Intel® as part of the EFI specification designed to replace MBR and BIOS. GPT identifies partitions using globally unique identifiers (GUIDs), also known as universally unique identifiers (UUIDs). The advantages of GPT include support for larger disks and no partition limits. The supported sizes for GPT disks can range from about 9 to 75 zettabytes.[^1] 19 | 20 | ## File systems 21 | 22 | There are two file systems that can be used to install GhostBSD, the UNIX® file system (UFS) and ZFS® (previously the Zettabyte file system). 23 | 24 | ### UFS 25 | 26 | UFS is derived from the original filesystem used in Version 7 UNIX. During its long history there have been two versions (UFS1 and UFS2), improvements, and features added. In the GhostBSD installer, there are options to use UFS2 with or without journaling and soft updates. These features can create a more robust system to better handle crashes and provide a snapshot ability.[^3] On average, UFS may require fewer resources than OpenZFS, but on most modern computers this should not typically be of concern. 27 | 28 | ### OpenZFS 29 | 30 | ZFS is a modern filesystem first created as part of the Solaris® operating system. Solaris and ZFS were released under open source licenses for a brief time. Eventually, both were placed back under closed source licenses. Prior to the license changes, ZFS was forked and developed by the open source community and is now used in various operating systems as OpenZFS.[^4] There are numerous benefits to using OpenZFS, such as, error checking, data compression and file system snapshots.[^5] 31 | 32 | ## Installing GhostBSD 33 | 34 | Select *Custom (Advanced partitioning)* and click "Next" to start the Partition Editor. 35 | 36 | ![Starting the partition editor.](images/custom-installation/1-custom-partitioning.png) 37 | 38 | ### Partition Scheme 39 | 40 | :::{important} 41 | It's possible that the disk will already have a partitioning scheme shown under the "System/Type" field in the Partition Editor. If this is the case, you can skip this step and proceed to the *Creating partitions* section below. 42 | ::: 43 | 44 | In the Partition Editor you will see the disks that are available. 45 | 46 | ![Selecting the installation disk.](images/custom-installation/2-no-partition-table.png) 47 | 48 | Select the disk you want to install to and click "Create" to choose a partition scheme. 49 | 50 | ![Creating a GPT.](images/custom-installation/3-select-gpt.png) 51 | 52 | After choosing the desired partitioning scheme, click "+ Add" to create that layout on the selected disk. The result should look similar to the image below. 53 | 54 | ![A partitioned disk with GPT.](images/custom-installation/4-with-partition-table.png) 55 | 56 | ### Creating partitions 57 | 58 | The default installation of GhostBSD will create three partitions. These are boot, root, and swap. There are a variety of different configurations including omitting swap or placing /home, /usr, or /var on their own partitions or disks. These variations can also involve using either UFS or OpenZFS on GPT or MBR partitioned disks with machines that are booted with BIOS or UEFI. The example below will manually create a layout that is similar the default installation. It will use OpenZFS on a GPT disk with a machine that is booted with UEFI. 59 | 60 | #### Boot partition 61 | 62 | The first partition to create is the boot partition. Select the free space under the disk label, here these values are "freespace1" and "ada0". Then, click "Create" to open the "Add a Partition" dialog. Select "UEFI" and change the size. Here were are using 200MB. Click "+ Add" to create the UEFI partition. 63 | 64 | ![Create the UEFI boot partition.](images/custom-installation/5-efi-partition.png) 65 | 66 | #### Root partition 67 | 68 | Next create the OpenZFS root partition. Again, select the free space and click "Create". In the "Add a Partition" dialog, select "ZFS" and enter the desired size of the partition. Click "+ Add" to create the OpenZFS root partition. The installer will automatically assign the correct mount points for the partition. 69 | 70 | :::{important} 71 | It is necessary to account for the size of the swap partition (if using one) and a small amount of unallocated storage at the end of the disk. This section is required for the GPT table and proper alignment of the sectors on the disk. The default installation leaves about 5MB unallocated. 72 | ::: 73 | 74 | ![Create the OpenZFS root partition.](images/custom-installation/6-zfs-partition.png) 75 | 76 | #### Swap Partition 77 | 78 | The final partition to create is for swap. Depending on you needs and the amount of RAM in the computer this partition can be omitted. Generally, a few GB for swap is helpful in the event that the computer exceeds the amount RAM installed. 79 | 80 | In the same manner as the previous partition, select the free space and Click "Create". In the "Add a Partition" dialog make sure "SWAP" is selected, allocate the desired amount of swap and click "+ Add" to create the partition. 81 | 82 | ![Create the swap partition.](images/custom-installation/7-swap-partition.png) 83 | 84 | #### Finishing the installation 85 | 86 | After the above steps, the disk should be partitioned in a similar format as below. Simply click "Next" to proceed with the rest of the installation as described in the [Full disk installation](full-disk-installation.md) guide starting with the *Boot loader* section. 87 | 88 | ![Completed disk partitioning.](images/custom-installation/8-completed-partitioning.png) 89 | 90 | [^1]: Roderick Smith, "Make the most of large drives with GPT and Linux," IBM, https://developer.ibm.com/tutorials/l-gpt/ (July 3, 2012). 91 | 92 | [^2]: Joe Keeley, "MBR vs. GPT: Which Should You Use for Your SSD?," MakeUseOf, https://www.makeuseof.com/tag/mbr-vs-gpt/ (April 5, 2022). 93 | 94 | [^3]: Wikipedia contributors, "Unix File System," Wikipedia, The Free Encyclopedia, https://en.wikipedia.org/w/index.php?title=Unix_File_System&oldid=1100924136 (accessed July 31, 2022). 95 | 96 | [^4]: Michael Dexter, "ZFS vs. OpenZFS," TrueNas, https://www.truenas.com/blog/zfs-vs-openzfs/ (June 18, 2019). 97 | 98 | [^5]: "Main Page," OpenZFS, https://openzfs.org/wiki/Main_Page (July 19, 2022). -------------------------------------------------------------------------------- /contributor/translations/translate-python.md: -------------------------------------------------------------------------------- 1 | # Python Tool Translation Guide 2 | 3 | This guide covers translating GhostBSD Python applications using the standard workflow implemented in update-station. 4 | 5 | ## Prerequisites 6 | 7 | - Python development environment 8 | - Git access to the repository 9 | - Text editor for .po files 10 | - gettext tools: `sudo pkg install gettext-tools` 11 | 12 | ## Setup.py Implementation 13 | 14 | GhostBSD Python tools use these custom setuptools commands (based on update-station): 15 | 16 | ```python 17 | import os 18 | import glob 19 | from setuptools import setup, Command 20 | from DistUtilsExtra.command.build_extra import build_extra 21 | from DistUtilsExtra.command.build_i18n import build_i18n 22 | from DistUtilsExtra.command.clean_i18n import clean_i18n 23 | 24 | class UpdateTranslationsCommand(Command): 25 | """Custom command to extract messages and update .po files.""" 26 | description = 'Extract messages to .pot and update .po' 27 | user_options = [] 28 | 29 | def initialize_options(self): 30 | pass 31 | 32 | def finalize_options(self): 33 | pass 34 | 35 | def run(self): 36 | pot_file = 'po/[tool-name].pot' 37 | po_files = glob.glob('po/*.po') 38 | 39 | # Extract messages to .pot file 40 | print("Extracting messages to .pot file...") 41 | os.system(f'xgettext --from-code=UTF-8 -L Python -o {pot_file} [tool_directory]/*.py [main-script]') 42 | 43 | # Update .po files 44 | print("Updating .po files with new translations...") 45 | for po_file in po_files: 46 | print(f"Updating {po_file}...") 47 | os.system(f'msgmerge -U {po_file} {pot_file}') 48 | print("Translation update complete.") 49 | 50 | class CreateTranslationCommand(Command): 51 | """Custom command to create a new .po file for a specific language.""" 52 | description = 'Create a new .po file for the specified language' 53 | user_options = [ 54 | ('locale=', 'l', 'Locale code for the new translation (e.g., fr_FR, pt_BR)') 55 | ] 56 | 57 | def initialize_options(self): 58 | self.locale = None 59 | 60 | def finalize_options(self): 61 | if self.locale is None: 62 | raise Exception("You must specify the locale code (e.g., --locale=fr_FR)") 63 | 64 | def run(self): 65 | pot_file = 'po/[tool-name].pot' 66 | po_dir = 'po' 67 | po_file = os.path.join(po_dir, f'{self.locale}.po') 68 | 69 | # Create .pot file if needed 70 | if not os.path.exists(pot_file): 71 | print("Extracting messages to .pot file...") 72 | os.system(f'xgettext --from-code=UTF-8 -L Python -o {pot_file} [tool_directory]/*.py [main-script]') 73 | 74 | # Create new .po file 75 | if not os.path.exists(po_file): 76 | print(f"Creating new {po_file} for locale '{self.locale}'...") 77 | os.makedirs(po_dir, exist_ok=True) 78 | os.system(f'msginit --locale={self.locale} --input={pot_file} --output-file={po_file}') 79 | else: 80 | print(f"PO file for locale '{self.locale}' already exists: {po_file}") 81 | 82 | setup( 83 | cmdclass={ 84 | 'create_translation': CreateTranslationCommand, 85 | 'update_translations': UpdateTranslationsCommand, 86 | 'build': build_extra, 87 | 'build_i18n': build_i18n, 88 | 'clean': clean_i18n 89 | } 90 | ) 91 | ``` 92 | 93 | ## Translation Workflow 94 | 95 | ### 1. Clone Repository 96 | ```bash 97 | git clone https://github.com/ghostbsd/[tool-name] 98 | cd [tool-name] 99 | ``` 100 | 101 | ### 2. Create New Translation 102 | ```bash 103 | python setup.py create_translation --locale=fr_FR 104 | ``` 105 | 106 | Creates `po/fr_FR.po` with proper locale settings. 107 | 108 | ### 3. Update Translations 109 | After code changes: 110 | ```bash 111 | python setup.py update_translations 112 | ``` 113 | 114 | Updates all .po files with new/changed strings. 115 | 116 | ### 4. Edit Translations 117 | Edit the .po file: 118 | ```po 119 | #: update_station/main.py:45 120 | msgid "Network Manager" 121 | msgstr "Gestionnaire de R�seau" 122 | ``` 123 | 124 | ### 5. Build and Test 125 | ```bash 126 | python setup.py build 127 | LANG=fr_FR.UTF-8 python3 [main-script] 128 | ``` 129 | 130 | ## Directory Structure 131 | 132 | ``` 133 | repository/ 134 | po/ 135 | [tool-name].pot # Template (generated) 136 | fr_FR.po # French (France) 137 | fr_CA.po # French (Canada) 138 | pt_BR.po # Portuguese (Brazil) 139 | build/ 140 | lib/ 141 | locale/ # Compiled .mo files 142 | setup.py # Translation commands 143 | ``` 144 | 145 | ## Locale Format 146 | 147 | Use full locale format `language_COUNTRY` following install-station standard: 148 | 149 | ### Supported Locales (from install-station) 150 | - `ar_EG` - Arabic (Egypt) 151 | - `bg_BG` - Bulgarian (Bulgaria) 152 | - `bn_BD` - Bengali (Bangladesh) 153 | - `ca_ES` - Catalan (Spain) 154 | - `cs_CZ` - Czech (Czech Republic) 155 | - `da_DK` - Danish (Denmark) 156 | - `de_DE` - German (Germany) 157 | - `el_GR` - Greek (Greece) 158 | - `en_GB` - English (United Kingdom) 159 | - `en_US` - English (United States) 160 | - `es_ES` - Spanish (Spain) 161 | - `es_MX` - Spanish (Mexico) 162 | - `et_EE` - Estonian (Estonia) 163 | - `eu_ES` - Basque (Spain) 164 | - `fi_FI` - Finnish (Finland) 165 | - `fr_CA` - French (Canada) 166 | - `fr_FR` - French (France) 167 | - `gl_ES` - Galician (Spain) 168 | - `he_IL` - Hebrew (Israel) 169 | - `hi_IN` - Hindi (India) 170 | - `hr_HR` - Croatian (Croatia) 171 | - `hu_HU` - Hungarian (Hungary) 172 | - `id_ID` - Indonesian (Indonesia) 173 | - `is_IS` - Icelandic (Iceland) 174 | - `it_IT` - Italian (Italy) 175 | - `ja_JP` - Japanese (Japan) 176 | - `ko_KR` - Korean (South Korea) 177 | - `lt_LT` - Lithuanian (Lithuania) 178 | - `lv_LV` - Latvian (Latvia) 179 | - `mk_MK` - Macedonian (North Macedonia) 180 | - `nb_NO` - Norwegian Bokmål (Norway) 181 | - `nl_NL` - Dutch (Netherlands) 182 | - `nn_NO` - Norwegian Nynorsk (Norway) 183 | - `pl_PL` - Polish (Poland) 184 | - `pt_BR` - Portuguese (Brazil) 185 | - `pt_PT` - Portuguese (Portugal) 186 | - `ro_RO` - Romanian (Romania) 187 | - `ru_RU` - Russian (Russia) 188 | - `sk_SK` - Slovak (Slovakia) 189 | - `sl_SI` - Slovenian (Slovenia) 190 | - `sr_RS` - Serbian (Serbia) 191 | - `sv_SE` - Swedish (Sweden) 192 | - `th_TH` - Thai (Thailand) 193 | - `tr_TR` - Turkish (Turkey) 194 | - `uk_UA` - Ukrainian (Ukraine) 195 | - `vi_VN` - Vietnamese (Vietnam) 196 | - `zh_CN` - Chinese (China) 197 | - `zh_TW` - Chinese (Taiwan) 198 | 199 | ## Repository Status 200 | 201 | ### Tools Using This Standard 202 | - **update-station** - Reference implementation 203 | - **install-station** - Same implementation 204 | 205 | ### Tools Needing Implementation 206 | - **networkmgr** - Needs migration to standard commands 207 | - **setup-station** - Needs translation commands added 208 | - **station-tweak** - Needs translation commands added 209 | - **software-station** - Needs translation commands added 210 | - **backup-station** - Needs migration from DistUtilsExtra 211 | - **gbi** - Needs translation commands added 212 | 213 | ## Best Practices 214 | 215 | - Use full `language_COUNTRY` locale format 216 | - Keep UI text concise for interface constraints 217 | - Test translations in actual application 218 | - Use consistent terminology across GhostBSD tools 219 | - Commit only .po files (not .pot or .mo files) 220 | - Run `update_translations` regularly after code changes 221 | 222 | ## Contributing 223 | 224 | 1. Fork repository 225 | 2. Create/update translations: `python setup.py create_translation --locale=fr_FR` 226 | 3. Edit .po files with translations 227 | 4. Build and test: `python setup.py build` 228 | 5. Commit only .po files 229 | 6. Submit pull request -------------------------------------------------------------------------------- /user/installation-guide/custom-installation-pl.md: -------------------------------------------------------------------------------- 1 | Instalacja niestandardowa 2 | =========================== 3 | 4 | Instalacja niestandardowa i pełna instalacja dysku GhostBSD zaczynają się w ten sam sposób. Proszę postępować zgodnie z przewodnikiem [Pełna instalacja dysku](full-disk-installation.md) do sekcji *Dyski i system plików*. Po dotarciu do tej sekcji, postępuj zgodnie z tym przewodnikiem, aby zakończyć instalację niestandardową. 5 | 6 | Celem tego przewodnika nie jest dostarczenie kroków dla każdej możliwej konfiguracji, ale zapewnienie pewnego kontekstu, który pomoże w niestandardowym partycjonowaniu i układach systemów plików. Sekcja [Instalacja GhostBSD](#installing-ghostbsd) zawiera kroki potrzebne do niestandardowej instalacji z zalecaną konfiguracją używającą UEFI, GPT i OpenZFS. 7 | 8 | ## Schematy partycjonowania 9 | 10 | W GhostBSD dostępne są dwa schematy partycjonowania, które są używane do dzielenia dysku na sekcje zwane slice’ami lub partycjami. Istnieje układ Master Boot Record (MBR) oraz układ GUID Partition Table (GPT). Ogólnie rzecz biorąc, dyski MBR są używane, jeśli maszyna uruchamia się z użyciem starszego systemu Basic Input/Output System (BIOS), natomiast dyski GPT są używane, gdy uruchamiana jest z nowszym Unified Extensible Firmware Interface (UEFI). UEFI może uruchamiać się z dysku GPT lub MBR, a w niektórych maszynach istnieje kod kompatybilności, który umożliwia BIOS-owi uruchamianie z dysków GPT, oprócz dysków MBR.[^1] 11 | 12 | ### MBR 13 | 14 | Istnieje kilka ograniczeń podczas używania starszego układu MBR, w tym ograniczenia dotyczące rozmiaru dysku i liczby możliwych partycji. MBR oficjalnie obsługuje tylko dyski o pojemności do dwóch terabajtów. Istnieje również limit czterech partycji podstawowych, ale można użyć partycji rozszerzonej, aby zwiększyć tę liczbę.[^2] 15 | 16 | ### GPT 17 | 18 | GPT jest nowszym schematem partycjonowania stworzonym przez Intel® jako część specyfikacji EFI, zaprojektowanym w celu zastąpienia MBR i BIOS. GPT identyfikuje partycje za pomocą globalnie unikalnych identyfikatorów (GUID), znanych również jako uniwersalnie unikalne identyfikatory (UUID). Zalety GPT obejmują wsparcie dla większych dysków i brak limitów partycji. Obsługiwane rozmiary dysków GPT mogą wynosić od około 9 do 75 zettabajtów.[^1] 19 | 20 | ## Systemy plików 21 | 22 | Istnieją dwa systemy plików, które można wykorzystać do zainstalowania GhostBSD: system plików UNIX® (UFS) i ZFS® (wcześniej system plików Zettabyte). 23 | 24 | ### UFS 25 | 26 | UFS pochodzi z oryginalnego systemu plików używanego w wersji 7 UNIX. W trakcie swojej długiej historii istniały dwie wersje (UFS1 i UFS2), poprawki i dodane funkcje. W instalatorze GhostBSD dostępne są opcje użycia UFS2 z lub bez dzienników i miękkich aktualizacji. Te funkcje mogą stworzyć bardziej solidny system, który lepiej radzi sobie z awariami i zapewnia możliwość tworzenia migawek.[^3] Średnio, UFS może wymagać mniej zasobów niż OpenZFS, ale na większości nowoczesnych komputerów nie powinno to być problemem. 27 | 28 | ### OpenZFS 29 | 30 | ZFS jest nowoczesnym systemem plików, który został pierwotnie stworzony jako część systemu operacyjnego Solaris®. Solaris i ZFS zostały wydane na krótko na licencjach open source. Ostatecznie obie technologie zostały ponownie objęte licencjami closed source. Przed zmianami licencyjnymi, ZFS zostało forkiem i rozwinięte przez społeczność open source i jest teraz używane w różnych systemach operacyjnych jako OpenZFS.[^4] Istnieje wiele korzyści z używania OpenZFS, takich jak sprawdzanie błędów, kompresja danych i migawki systemu plików.[^5] 31 | 32 | ## Instalacja GhostBSD 33 | 34 | Wybierz *Niestandardowa (Zaawansowane partycjonowanie)* i kliknij "Dalej", aby rozpocząć Edytor partycji. 35 | 36 | ![Rozpoczęcie edytora partycji.](images/custom-installation/1-custom-partitioning.png) 37 | 38 | ### Schemat partycjonowania 39 | 40 | :::{important} 41 | Możliwe, że dysk już ma schemat partycjonowania pokazany w polu "System/Typ" w Edytorze partycji. Jeśli tak jest, możesz pominąć ten krok i przejść do sekcji *Tworzenie partycji* poniżej. 42 | ::: 43 | 44 | W Edytorze partycji zobaczysz dostępne dyski. 45 | 46 | ![Wybór dysku instalacyjnego.](images/custom-installation/2-no-partition-table.png) 47 | 48 | Wybierz dysk, na którym chcesz zainstalować i kliknij "Utwórz", aby wybrać schemat partycjonowania. 49 | 50 | ![Tworzenie GPT.](images/custom-installation/3-select-gpt.png) 51 | 52 | Po wybraniu pożądanego schematu partycjonowania, kliknij "+ Dodaj", aby utworzyć ten układ na wybranym dysku. Wynik powinien wyglądać podobnie do poniższego obrazu. 53 | 54 | ![Dysk z partycjonowaniem GPT.](images/custom-installation/4-with-partition-table.png) 55 | 56 | ### Tworzenie partycji 57 | 58 | Domyślna instalacja GhostBSD utworzy trzy partycje. Są to partycja boot, root i swap. Istnieje wiele różnych konfiguracji, w tym pominięcie swapu lub umieszczanie /home, /usr lub /var na własnych partycjach lub dyskach. Te warianty mogą również obejmować użycie UFS lub OpenZFS na dyskach GPT lub MBR z maszynami uruchamianymi z BIOS lub UEFI. Poniższy przykład ręcznie utworzy układ podobny do domyślnej instalacji. Użyje OpenZFS na dysku GPT z maszyną uruchamianą z UEFI. 59 | 60 | #### Partycja boot 61 | 62 | Pierwszą partycją do utworzenia jest partycja boot. Wybierz wolne miejsce pod etykietą dysku, tutaj te wartości to "freespace1" i "ada0". Następnie kliknij "Utwórz", aby otworzyć okno dialogowe "Dodaj partycję". Wybierz "UEFI" i zmień rozmiar. Używamy tutaj 200MB. Kliknij "+ Dodaj", aby utworzyć partycję UEFI. 63 | 64 | ![Utwórz partycję boot UEFI.](images/custom-installation/5-efi-partition.png) 65 | 66 | #### Partycja root 67 | 68 | Następnie utwórz partycję root OpenZFS. Ponownie wybierz wolne miejsce i kliknij "Utwórz". W oknie dialogowym "Dodaj partycję" wybierz "ZFS" i wpisz pożądany rozmiar partycji. Kliknij "+ Dodaj", aby utworzyć partycję root OpenZFS. Instalator automatycznie przypisze odpowiednie punkty montowania dla partycji. 69 | 70 | :::{important} 71 | Należy uwzględnić rozmiar partycji swap (jeśli używasz jednej) oraz niewielką ilość nieprzydzielonego miejsca na końcu dysku. Ta sekcja jest wymagana dla tabeli GPT i prawidłowego wyrównania sektorów na dysku. Domyślna instalacja pozostawia około 5MB nieprzydzielonego miejsca. 72 | ::: 73 | 74 | ![Utwórz partycję root OpenZFS.](images/custom-installation/6-zfs-partition.png) 75 | 76 | #### Partycja swap 77 | 78 | Ostatnią partycją do utworzenia jest partycja swap. W zależności od twoich potrzeb i ilości RAM w komputerze, ta partycja może zostać pominięta. Ogólnie, kilka GB dla swapu jest pomocne w przypadku, gdy komputer przekroczy zainstalowaną ilość RAM. 79 | 80 | W ten sam sposób, co poprzednia partycja, wybierz wolne miejsce i kliknij "Utwórz". W oknie dialogowym "Dodaj partycję" upewnij się, że wybrano "SWAP", przydziel pożądany rozmiar swapu i kliknij "+ Dodaj", aby utworzyć partycję. 81 | 82 | ![Utwórz partycję swap.](images/custom-installation/7-swap-partition.png) 83 | 84 | #### Zakończenie instalacji 85 | 86 | Po wykonaniu powyższych kroków dys 87 | 88 | k powinien być partycjonowany w podobnym formacie jak poniżej. Po prostu kliknij "Dalej", aby kontynuować resztę instalacji, zgodnie z opisem w przewodniku [Pełna instalacja dysku](full-disk-installation.md), zaczynając od sekcji *Boot loader*. 89 | 90 | ![Zakończone partycjonowanie dysku.](images/custom-installation/8-completed-partitioning.png) 91 | 92 | [^1]: Roderick Smith, "Make the most of large drives with GPT and Linux," IBM, https://developer.ibm.com/tutorials/l-gpt/ (3 lipca 2012). 93 | 94 | [^2]: Joe Keeley, "MBR vs. GPT: Which Should You Use for Your SSD?," MakeUseOf, https://www.makeuseof.com/tag/mbr-vs-gpt/ (5 kwietnia 2022). 95 | 96 | [^3]: Wikipedia contributors, "Unix File System," Wikipedia, The Free Encyclopedia, https://en.wikipedia.org/w/index.php?title=Unix_File_System&oldid=1100924136 (dostęp 31 lipca 2022). 97 | 98 | [^4]: Michael Dexter, "ZFS vs. OpenZFS," TrueNas, https://www.truenas.com/blog/zfs-vs-openzfs/ (18 czerwca 2019). 99 | 100 | [^5]: "Main Page," OpenZFS, https://openzfs.org/wiki/Main_Page (19 lipca 2022). -------------------------------------------------------------------------------- /contributor/maintenance-release/maintaining-src-tree.md: -------------------------------------------------------------------------------- 1 | # Maintaining GhostBSD Src from FreeBSD SRC 2 | 3 | ## Purpose 4 | This guide explains how to keep the GhostBSD src tree (https://github.com/ghostbsd/ghostbsd-src) current with the upstream FreeBSD src tree (https://github.com/freebsd/freebsd-src), manage stable and releng branches, resolve merge conflicts, and test changes before submission. 5 | 6 | ## Prerequisites 7 | - Git installed and configured with SSH access to GitHub 8 | - Basic understanding of Git commands and FreeBSD src structure 9 | - A local working directory (e.g., `~/ghostbsd-src`) 10 | - Understanding of FreeBSD's branching model (main → stable → releng) 11 | 12 | --- 13 | 14 | ## Step-by-Step Instructions 15 | 16 | ### 1. Clone the Repository and Configure Remotes 17 | Clone the GhostBSD src repository using SSH: 18 | ```shell 19 | git clone git@github.com:ghostbsd/ghostbsd-src.git 20 | cd ghostbsd-src 21 | ``` 22 | Add the FreeBSD src repository as a remote: 23 | ```shell 24 | git remote add freebsd https://github.com/freebsd/freebsd-src.git 25 | ``` 26 | Verify the remotes: 27 | ```shell 28 | git remote -v 29 | ``` 30 | Expected output: 31 | ``` 32 | freebsd https://github.com/freebsd/freebsd-src.git (fetch) 33 | freebsd https://github.com/freebsd/freebsd-src.git (push) 34 | origin git@github.com:ghostbsd/ghostbsd-src.git (fetch) 35 | origin git@github.com:ghostbsd/ghostbsd-src.git (push) 36 | ``` 37 | 38 | **Note**: If the `freebsd` remote is already set, skip the `git remote add` step. 39 | 40 | --- 41 | 42 | ### 2. Understanding Branch Management Strategy 43 | 44 | GhostBSD follows a specific branching strategy to ensure safe integration with FreeBSD updates: 45 | 46 | #### Branch Creation Timeline: 47 | 1. **Update `main`** before FreeBSD creates `stable/15` 48 | 2. **Create `stable/15`** from updated `main` after FreeBSD creates their `stable/15` 49 | 3. **Update `stable/14`** before FreeBSD creates any `releng/14.*` 50 | 4. **Create `releng/14.*`** from updated `stable/14` after FreeBSD creates their `releng/14.*` 51 | 52 | #### Safe Merge Strategy: 53 | - Always create a separate merge branch (e.g., `merge-freebsd/stable/15`) before merging 54 | - Test the merge in the separate branch first 55 | - Only create PR after conflicts are resolved and testing passes 56 | 57 | --- 58 | 59 | ### 3. Working with Main Branch 60 | 61 | #### Update Main Branch: 62 | ```shell 63 | git checkout main 64 | git pull origin main 65 | git fetch freebsd 66 | git checkout -b merge-freebsd-main 67 | git merge freebsd/main 68 | ``` 69 | 70 | **If conflicts occur**: Resolve them following the conflict resolution guidelines below. 71 | 72 | **After successful merge and testing**: 73 | ```shell 74 | # Create PR from merge-freebsd-main to main 75 | git push origin merge-freebsd-main 76 | # Create PR on GitHub 77 | ``` 78 | 79 | --- 80 | 81 | ### 4. Creating and Maintaining Stable Branches 82 | 83 | #### When FreeBSD Creates a New Stable Branch (e.g., stable/15): 84 | 85 | 1. **First, ensure main is up-to-date** (follow step 3) 86 | 2. **Create the stable branch from main**: 87 | ```shell 88 | git checkout main 89 | git pull origin main # Ensure main is current 90 | git checkout -b stable/15 91 | git push origin stable/15 92 | ``` 93 | 94 | 3. **Create merge branch and sync with FreeBSD**: 95 | ```shell 96 | git checkout stable/15 97 | git checkout -b merge-freebsd/stable/15 98 | git fetch freebsd 99 | git merge freebsd/stable/15 100 | ``` 101 | 102 | #### For Existing Stable Branches: 103 | ```shell 104 | git checkout stable/14 105 | git pull origin stable/14 106 | git checkout -b merge-freebsd/stable/14 107 | git fetch freebsd 108 | git merge freebsd/stable/14 109 | ``` 110 | 111 | --- 112 | 113 | ### 5. Creating and Maintaining Releng Branches 114 | 115 | #### When FreeBSD Creates a New Releng Branch (e.g., releng/14.5): 116 | 117 | 1. **First, ensure stable/14 is up-to-date**: 118 | ```shell 119 | git checkout stable/14 120 | git pull origin stable/14 121 | git fetch freebsd 122 | git checkout -b merge-freebsd/stable/14 123 | git merge freebsd/stable/14 124 | # Resolve conflicts, test, create PR for stable/14 first 125 | ``` 126 | 127 | 2. **Create releng branch from updated stable**: 128 | ```shell 129 | git checkout stable/14 130 | git pull origin stable/14 # After stable/14 PR is merged 131 | git checkout -b releng/14.5 132 | git push origin releng/14.5 133 | ``` 134 | 135 | 3. **Create merge branch and sync with FreeBSD**: 136 | ```shell 137 | git checkout releng/14.5 138 | git checkout -b merge-freebsd/releng/14.5 139 | git fetch freebsd 140 | git merge freebsd/releng/14.5 141 | ``` 142 | 143 | #### Updating Releng Branches for Patch Levels (p1, p2, etc.): 144 | 145 | When FreeBSD adds patch levels to existing releng branches (e.g., releng/14.2-p1): 146 | 147 | 1. **Update existing releng branch**: 148 | ```shell 149 | git checkout releng/14.2 150 | git pull origin releng/14.2 151 | git checkout -b merge-freebsd/releng/14.2-p1 152 | git fetch freebsd 153 | git merge freebsd/releng/14.2 154 | ``` 155 | 156 | 2. **Update GhostBSD version**: 157 | ```shell 158 | # Update sys/conf/package-version to reflect new patch level 159 | # Example: 25.01.R14.2p0 → 25.01.R14.2p1 160 | # See the [GhostBSD Versioning Guide](versioning-guide.md) for version format details 161 | ``` 162 | 163 | 3. **Test and create PR**: 164 | ```shell 165 | # After resolving conflicts and testing 166 | git push origin merge-freebsd/releng/14.2-p1 167 | # Create PR to merge into releng/14.2 168 | ``` 169 | 170 | --- 171 | 172 | ### 6. Resolve Merge Conflicts 173 | 174 | Conflicts typically occur in GhostBSD-specific modifications. To find conflicts: 175 | ```shell 176 | grep -R '<<<<<<< HEAD' . 177 | ``` 178 | 179 | **Resolution Guidelines**: 180 | - **Always preserve GhostBSD customizations**: Keep our specific changes and fixes 181 | - **If uncertain about a conflict**: Ask for guidance rather than guessing 182 | - **Check the conflict context**: Understand what each side is trying to achieve 183 | - **Test thoroughly**: Conflicts can introduce subtle bugs 184 | 185 | Example conflict resolution: 186 | ``` 187 | <<<<<<< HEAD 188 | # GhostBSD-specific changes (keep these) 189 | ======= 190 | # FreeBSD changes (evaluate if compatible) 191 | >>>>>>> freebsd/main 192 | ``` 193 | 194 | --- 195 | 196 | ### 7. Testing Changes 197 | 198 | Before submitting any changes, test the build: 199 | ```shell 200 | make buildworld 201 | make buildkernel 202 | ``` 203 | 204 | **Important**: Both commands must complete successfully before creating a PR. 205 | 206 | If build errors occur: 207 | 1. Review the error messages 208 | 2. Check if GhostBSD customizations are conflicting with FreeBSD changes 209 | 3. Resolve the issues 210 | 4. Re-test the build 211 | 212 | --- 213 | 214 | ### 8. Submit Changes 215 | 216 | After successful testing: 217 | 218 | 1. **Stage all changes**: 219 | ```shell 220 | git add -A 221 | ``` 222 | 223 | 2. **Commit changes**: 224 | ```shell 225 | git commit -m "Merge FreeBSD [branch] updates 226 | 227 | - Resolved conflicts in [files] 228 | - Preserved GhostBSD customizations 229 | - Build tested successfully" 230 | ``` 231 | 232 | 3. **Push merge branch**: 233 | ```shell 234 | git push origin merge-freebsd/[branch-name] 235 | ``` 236 | 237 | 4. **Create Pull Request**: 238 | - Create PR from `merge-freebsd/[branch-name]` to target branch 239 | - Describe resolved conflicts and testing performed 240 | - Await review and approval 241 | 242 | :::{note} 243 | Never push directly to `main`, `stable/*`, or `releng/*` branches. Always use the merge branch and PR workflow. 244 | ::: 245 | 246 | --- 247 | 248 | ## Branch Management Best Practices 249 | 250 | ### Timing Guidelines: 251 | - **Monitor FreeBSD announcements** for new stable/releng branch creation 252 | - **Update GhostBSD branches before** FreeBSD creates new branches when possible 253 | - **Create branches promptly** after FreeBSD creates them to minimize drift 254 | 255 | ### Testing Requirements: 256 | - **Always run full build tests** (`make buildworld buildkernel`) 257 | - **Test in merge branches first** before creating PRs 258 | - **Document any build issues** and their resolutions 259 | 260 | ### Conflict Resolution: 261 | - **When in doubt, ask**: Don't guess about complex conflicts 262 | - **Preserve GhostBSD identity**: Keep our customizations and branding 263 | - **Document decisions**: Note why certain changes were kept or modified 264 | 265 | --- 266 | 267 | ## Common Issues and Solutions 268 | 269 | - **Build Failures**: Check for GhostBSD-specific patches that may conflict with FreeBSD updates 270 | - **Complex Conflicts**: Create a backup branch before attempting resolution 271 | - **Branch Creation Timing**: If you miss the optimal timing, additional conflicts may occur but can still be resolved 272 | - **Testing Environment**: Ensure your build environment matches the target architecture 273 | 274 | --- 275 | 276 | ## Emergency Procedures 277 | 278 | If a merge branch becomes too complex: 279 | 1. **Create a backup**: `git checkout -b backup-merge-branch` 280 | 2. **Start fresh**: Return to the target branch and create a new merge branch 281 | 3. **Cherry-pick specific commits**: Apply only the changes that worked 282 | 4. **Ask for help**: Complex situations may require collaborative resolution -------------------------------------------------------------------------------- /user/installation-guide/getting-started.md: -------------------------------------------------------------------------------- 1 | Getting started 2 | =============== 3 | 4 | ## Status 5 | 6 | GhostBSD is available for general use. 7 | 8 | ## System requirements 9 | 10 | * 2 GHz dual core Intel/AMD 64-bit processor 11 | * 8 GiB RAM (system memory for physical and virtualized installs) 12 | * VGA capable of 1024x768 screen resolution 13 | * Network connection 14 | * 15 GiB of storage 15 | * Either a CD/DVD drive or a USB port for booting the installer media 16 | 17 | **Note**: While the system may boot with less RAM, 8 GiB is recommended for reliable installation and operation. Systems with 4 GiB or less may experience issues during installation due to video buffer usage and installer memory requirements. 18 | 19 | Please refer to [FreeBSD Hardware Compatibility](https://docs.freebsd.org/en/books/faq/#hardware) for more information on individual components. 20 | 21 | ### Tested hardware 22 | 23 | GhostBSD is known to boot to a graphical desktop on the following machines. Auxiliary functionality such as wireless networking, sound over HDMI, sleep, graphics acceleration, etc. has not yet been tested systematically. 24 | 25 | Please contact us if you would like to sponsor the project with a hardware donation. We are especially looking for Lenovo devices from the previous generations that should be available second-hand inexpensively. 26 | 27 | To see Hardware Probes of systems running GhostBSD, please see the [GhostBSD Hardware Database](http://bsd-hardware.info/?d=GhostBSD&view=computers) provided by bsd-hardware.info. It is reasonable to assume that every system listed there can at least successfully boot GhostBSD. Auxiliary functionality such as wireless networking, sound over HDMI, sleep, graphics acceleration, etc. may or may not be working. 28 | 29 | ### Networking hardware 30 | 31 | Not all networking devices may be supported by GhostBSD yet. In those cases, you may want to consider using a USB-based networking device. GhostBSD developers currently have access to the following USB-based networking devices, which are known to work: 32 | 33 | * [USB 802.11n WLAN adapters based on `ID 0bda:8176 Realtek Semiconductor Corp. RTL8188CUS`](https://vermaden.wordpress.com/2020/10/30/realtek-usb-wifi-review/) 34 | * USB wired Ethernet adapters based on `ID 0b95:772b ASIX Electronics Corp. AX88772B`, driven by [axe(4)](https://man.freebsd.org/cgi/man.cgi?query=axe&sektion=4&manpath=freebsd). 35 | 36 | ## Getting an ISO 37 | 38 | The **GhostBSD** ISO image is available for download [here](https://www.ghostbsd.org/download). 39 | 40 | ~~Experimental development images are available for download [here](https://download.ghostbsd.org/development/amd64/latest/).~~ 41 | 42 | ## Creating a bootable USB flash drive 43 | 44 | After downloading the appropriate ISO image, copy it to a USB flash drive using one of the methods described below. 45 | 46 | **Please Note**: 47 | * GhostBSD-YY.PP-RXX.YpL.iso represents the current GhostBSD ISO, for example, GhostBSD-25.01-R14.2p2.iso. 48 | * Likewise, X is a number or letter that will change based on the number of drives attached to the computer, for example, /dev/da-1 or /dev/sdb. 49 | * It may also be necessary to run the commands below as root using a tool like sudo. 50 | 51 | **On FreeBSD** 52 | ``` 53 | dd if=/path/to/GhostBSD-YY.PP-RXX.YpL.iso of=/dev/daX bs=3m 54 | ``` 55 | 56 | **On OpenBSD** 57 | ``` 58 | dd if=/path/to/GhostBSD-YY.PP-RXX.YpL.iso of=/dev/rsdXc bs=3m 59 | ``` 60 | 61 | **On NetBSD** 62 | ``` 63 | dd if=/path/to/GhostBSD-YY.PP-RXX.YpL.iso of=/dev/rsdXd bs=3m 64 | ``` 65 | 66 | **On Linux** 67 | ``` 68 | dd if=/path/to/GhostBSD-YY.PP-RXX.YpL.iso of=/dev/sdX bs=3M 69 | ``` 70 | 71 | **On macOS** 72 | ``` 73 | dd if=/path/to/GhostBSD-YY.PP-RXX.YpL.iso of=/dev/diskX bs=3m 74 | ``` 75 | 76 | **On Windows** 77 | * Download and run the imaging tool, Rufus, from the [website](https://rufus.ie/en/). 78 | * Insert the USB flash drive. 79 | * Make sure the flash drive is shown in Rufus under **Device**. 80 | * Click "SELECT" and choose the GhostBSD ISO file. 81 | * Click "START". 82 | 83 | A list of additional live USB creation tools can be found on [Wikpedia](https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems). 84 | 85 | The steps described above will create a bootable GhostBSD system on a USB flash drive. To start a live session, insert the flash drive into the computer, reboot, and select the flash drive as the boot device. Further information can be found [here](#starting-the-ghostbsd-live-system). 86 | 87 | Users have also reported success with [Ventoy](https://ventoy.net) 88 | 89 | ## Virtualization environments 90 | 91 | ``` .. note:: 92 | We recommend running GhostBSD on real hardware ("bare metal") if possible. This should give you the best possible performance and hardware support. 93 | ``` 94 | 95 | Users have reported success in running GhostBSD in the following virtualization environments: 96 | 97 | * VirtualBox host (on FreeBSD and macOS), known to work in BIOS and EFI mode 98 | 99 | * VMware host (on Windows), possibly only working in BIOS mode? 100 | 101 | * QEMU host (on Linux), works in both BIOS and EFI modes (see below). Note that for acceptable performance, QEMU needs KVM which is currently not available on FreeBSD hosts yet 102 | 103 | * Parallels host, reported to work in EFI mode (see below) 104 | 105 | * Proxmox VE 106 | 107 | Please note: 108 | 109 | * The VM needs to be __64-bit__ 110 | * The VM needs __at least 8 GB of RAM__ 111 | * The VM needs __at least 2 CPU cores__ 112 | * The boot process takes longer than you might expect; boot in verbose mode to see the details 113 | * For best results set **EFI/UEFI** boot mode (not BIOS) 114 | 115 | Please report back about the results on your virtualization environment. 116 | 117 | ### QEMU 118 | 119 | Create an 8 GiB (or larger) `ghostbsd.img` image file on which you can install the system: 120 | 121 | ``` 122 | $ pwd 123 | /home/user 124 | $ mkdir -p .qemu/ghostbsd 125 | $ fallocate -l $(( 8*1024*1024*1024 )) .qemu/ghostbsd/ghostbsd.img 126 | ``` 127 | 128 | Then, boot GhostBSD: 129 | 130 | ``` 131 | qemu-system-x86_64 -machine type=q35,accel=kvm \ 132 | -enable-kvm -cpu host -smp 2 -m 8192 \ 133 | -device virtio-net,netdev=vmnic -netdev user,id=vmnic,hostfwd=tcp::5222-:22 \ 134 | -vga std -soundhw hda -no-quit \ 135 | -drive format=raw,file=${HOME}/.qemu/ghostbsd/ghostbsd.img \ 136 | -drive format=raw,file=${HOME}/Downloads/ghostbsd.iso \ 137 | -boot menu=on 138 | ``` 139 | 140 | When QEMU starts, press `esc` and select `2` to boot the ISO. 141 | 142 | Use the __Install GhostBSD__ utility to install GhostBSD do the disk image. 143 | 144 | Then restart QEMU, you now remove the last two options from the above command. 145 | 146 | Notes 147 | 148 | * The `hostfwd=` option creates a port forward from your host port `5222` to the Qemu VM port `22`. 149 | * Unfortunately the qemu-system-x86_64 USB tablet options do not work; you will need to press Ctrl+Alt+g to release the mouse pointer from the QEMU window 150 | * To make QEMU full screen, press Ctrl+Alt+F 151 | 152 | To boot/install GhostBSD in UEFI mode, first install [OVMF Open Virtual Machine Firmware](https://github.com/tianocore/tianocore.github.io/wiki/OVMF) on your host side. The package name for Fedora 32 is `edk2-ovmf` 153 | 154 | Then add these two `qemu-system-x86_64` options: 155 | ``` 156 | -bios /usr/share/edk2/ovmf/OVMF_CODE.fd \ 157 | -smbios type=0,vendor=0vendor,version=0version,date=0date,release=0.0,uefi=on \ 158 | ``` 159 | 160 | ### Parallels 161 | 162 | * Select Hardware > Boot Order. 163 | * Expand **Advanced Settings**. Set **BIOS** to "EFI 64-bit" and in the Boot flags field, enter `vm.bios.efi=1`. 164 | 165 | ![Screenshot](https://docs.01.org/clearlinux/latest/zh_CN/_images/parallels-07.png) 166 | 167 | ### Proxmox VE 168 | 169 | * Memory: 8GB (not ballooned) 170 | * Processors: 2 (1 socket 2 cores) 171 | * BIOS: OVMF (UEFI) 172 | * Display: Default (VGA) 173 | * Machine: q35 174 | * SATA Controller: VirtIO SATA for attaching virtual disk to (to install the system on) 175 | * CD Drive: GhostBSD ISO 176 | * Hard Disk: At least 8GB Raw 177 | * Network Device: VirtIO 178 | 179 | To set resolution, press F2 at boot to access OVMF settings. Select 'Device Manager > OVMF Platform Configuration > Change Preferred', save and reboot. 180 | 181 | ### VirtualBox 182 | 183 | Install VirtualBox using your package manager or from the [website](https://virtualbox.org). Then, launch the VirtualBox Manager and select Tools > New to create a virtual machine with the following settings. 184 | 185 | * Name and operating system 186 | * Enter a **Name** for the virtual machine 187 | * Set **Type** to "FreeBSD" 188 | * Set **Version** to "FreeBSD (64-bit)" 189 | * Memory size 190 | * Increase the **RAM** to at least 8GB (8192MB) 191 | * Hard disk 192 | * Default settings are recommended. 193 | * Hard disk file type 194 | * Default settings are recommended. 195 | * Storage on physical hard disk 196 | * Default settings are recommended. 197 | * File location and size 198 | * Default settings are okay but it may be desirable to increase the maximum size of the virtual storage. 199 | 200 | After completing the above steps, the virtual machine will be created. In the VirtualBox Manager, select the new virtual machine and open the Settings screen. Edit the settings described below. 201 | 202 | * System > Motherboard 203 | * Under **Extended Features** select "Enable EFI (special OSes only) 204 | * System > Processor 205 | * Set **Prosessor(s)** to at least 2 CPUs 206 | * Display > Screen 207 | * Change **Graphics Controller** to VBoxSVGA 208 | * Storage 209 | * Under **Storage Devices** select the Optical Drive (CD icon) 210 | * Under **Attributes** click the CD icon to open a drop down menu. 211 | * Select "Choose a disk file..." and locate the downloaded GhostBSD iso file. 212 | 213 | Click "OK" to save the changes. Finally, in the VirtualBox Manager, select Start. The GhostBSD live system will boot into the Mate desktop environment. Click "Install GhostBSD" to start the installer. After installation, either reboot or shutdown the virtual machine and remove the ISO from the optical drive before the next boot. 214 | -------------------------------------------------------------------------------- /user/installation-guide/getting-started-pl.md: -------------------------------------------------------------------------------- 1 | Rozpoczęcie pracy 2 | ================= 3 | 4 | ## Status 5 | 6 | GhostBSD jest dostępny do ogólnego użytku. 7 | 8 | ## Wymagania systemowe 9 | 10 | * Dwurdzeniowy procesor Intel/ARM 64-bit o taktowaniu 2 GHz 11 | * 4 GiB RAM (pamięci systemowej dla instalacji fizycznych i wirtualnych) 12 | * Karta VGA obsługująca rozdzielczość 1024x768 13 | * Połączenie sieciowe 14 | * 15 GiB miejsca na dysku 15 | * Napęd CD/DVD lub port USB do uruchomienia nośnika instalacyjnego 16 | 17 | W przyszłości mogą pojawić się wersje dla innych architektur procesorowych. Chcemy znacznie obniżyć wymagania dotyczące pamięci RAM. 18 | 19 | Więcej informacji na temat kompatybilności sprzętowej można znaleźć w [FAQ FreeBSD o kompatybilności sprzętowej](https://docs.freebsd.org/en/books/faq/#hardware). 20 | 21 | ### Przetestowany sprzęt 22 | 23 | GhostBSD jest znany z uruchamiania graficznego pulpitu na następujących maszynach. Funkcjonalność dodatkowa, taka jak bezprzewodowa sieć, dźwięk przez HDMI, uśpienie, przyspieszenie grafiki itp., nie została jeszcze systematycznie przetestowana. 24 | 25 | Prosimy o kontakt, jeśli chcieliby Państwo wesprzeć projekt darowizną sprzętową. Szczególnie interesują nas urządzenia Lenovo z poprzednich generacji, które powinny być dostępne w niskich cenach na rynku wtórnym. 26 | 27 | Aby zobaczyć Proby Sprzętowe systemów działających na GhostBSD, prosimy odwiedzić [Bazę Sprzętową GhostBSD](http://bsd-hardware.info/?d=GhostBSD&view=computers) dostarczoną przez bsd-hardware.info. Można założyć, że każdy system wymieniony tam jest przynajmniej zdolny do uruchomienia GhostBSD. Dodatkowa funkcjonalność, taka jak sieć bezprzewodowa, dźwięk przez HDMI, uśpienie, przyspieszenie grafiki itp., może działać lub nie. 28 | 29 | ### Sprzęt sieciowy 30 | 31 | Nie wszystkie urządzenia sieciowe mogą być jeszcze obsługiwane przez GhostBSD. W takich przypadkach warto rozważyć użycie urządzenia sieciowego na bazie USB. Programiści GhostBSD mają obecnie dostęp do następujących urządzeń sieciowych na bazie USB, które są znane z działania: 32 | 33 | * [Adaptery USB 802.11n WLAN oparte na `ID 0bda:8176 Realtek Semiconductor Corp. RTL8188CUS`](https://vermaden.wordpress.com/2020/10/30/realtek-usb-wifi-review/) 34 | * Przewodowe adaptery Ethernet USB oparte na `ID 0b95:772b ASIX Electronics Corp. AX88772B`, obsługiwane przez [axe(4)](https://man.freebsd.org/cgi/man.cgi?query=axe&sektion=4&manpath=freebsd). 35 | 36 | ## Pobieranie obrazu ISO 37 | 38 | Obraz ISO **GhostBSD** jest dostępny do pobrania [tutaj](https://www.ghostbsd.org/download). 39 | 40 | Eksperymentalne obrazy rozwojowe są dostępne do pobrania [tutaj](https://download.ghostbsd.org/development/amd64/latest/). 41 | 42 | ## Tworzenie bootowalnej pamięci USB 43 | 44 | Po pobraniu odpowiedniego obrazu ISO, skopiuj go na pamięć USB, korzystając z jednej z opisanych poniżej metod. 45 | 46 | **Uwaga:** 47 | * GhostBSD-YY.MM.DD.iso reprezentuje aktualny obraz ISO GhostBSD, na przykład, GhostBSD-23.06.18.iso. 48 | * Podobnie, X to liczba lub litera, która zmienia się w zależności od liczby dysków podłączonych do komputera, na przykład, /dev/da-1 lub /dev/sdb. 49 | * Może być również konieczne uruchomienie poniższych poleceń jako użytkownik root, używając narzędzia takiego jak sudo. 50 | 51 | **Na \*BSD** 52 | ``` 53 | dd if=/path/to/GhostBSD-YY.MM.DD.iso of=/dev/daX bs=3m 54 | ``` 55 | 56 | **Na Linuxie** 57 | ``` 58 | dd if=/path/to/GhostBSD-YY.MM.DD.iso of=/dev/sdX bs=3M 59 | ``` 60 | 61 | **Na macOS** 62 | ``` 63 | dd if=/path/to/GhostBSD-YY.MM.DD.iso of=/dev/diskX bs=3m 64 | ``` 65 | 66 | **Na Windows** 67 | * Pobierz i uruchom narzędzie do tworzenia obrazów, Rufus, ze [strony internetowej](https://rufus.ie/en/). 68 | * Włóż pamięć USB. 69 | * Upewnij się, że pamięć USB jest wyświetlana w Rufusie pod **Urządzenie**. 70 | * Kliknij "WYBIERZ" i wybierz plik ISO GhostBSD. 71 | * Kliknij "START". 72 | 73 | Listę dodatkowych narzędzi do tworzenia bootowalnych systemów USB można znaleźć na [Wikipedii](https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems). 74 | 75 | Opisane powyżej kroki utworzą bootowalny system GhostBSD na pamięci USB. Aby rozpocząć sesję live, włóż pamięć USB do komputera, uruchom ponownie system i wybierz pamięć USB jako urządzenie startowe. Więcej informacji można znaleźć [tutaj](https://wiki.ghostbsd.org/index.php/Starting_GhostBSD_Live_Media). 76 | 77 | ## Środowiska wirtualizacyjne 78 | 79 | ``` .. note:: 80 | Zalecamy uruchamianie GhostBSD na prawdziwym sprzęcie ("bare metal"), jeśli to możliwe. Powinno to zapewnić najlepszą wydajność i wsparcie dla sprzętu. 81 | ``` 82 | 83 | Użytkownicy zgłaszali, że GhostBSD działa pomyślnie w następujących środowiskach wirtualizacyjnych: 84 | 85 | * Host VirtualBox (na FreeBSD i macOS), znany jako działający w trybie BIOS i EFI 86 | 87 | * Host VMware (na Windowsie), możliwe, że działa tylko w trybie BIOS? 88 | 89 | * Host QEMU (na Linuxie), działa w obu trybach BIOS i EFI (patrz poniżej). Należy pamiętać, że dla akceptowalnej wydajności QEMU potrzebuje KVM, który obecnie nie jest dostępny na hostach FreeBSD 90 | 91 | * Host Parallels, zgłaszany jako działający w trybie EFI (patrz poniżej) 92 | 93 | * Proxmox VE 94 | 95 | Proszę zwrócić uwagę: 96 | 97 | * VM musi być __64-bitowy__ 98 | * VM potrzebuje __co najmniej 4 GB pamięci RAM__ 99 | * VM potrzebuje __co najmniej 2 rdzenie CPU__ 100 | * Proces uruchamiania trwa dłużej, niż można by się spodziewać; uruchom w trybie verbose, aby zobaczyć szczegóły 101 | * Dla najlepszych wyników ustaw tryb **EFI/UEFI** (nie BIOS) 102 | 103 | Prosimy o zgłaszanie wyników w swoim środowisku wirtualizacyjnym. 104 | 105 | ### QEMU 106 | 107 | Utwórz plik obrazu `ghostbsd.img` o rozmiarze 8 GiB (lub większym), na którym można zainstalować system: 108 | 109 | ```bash 110 | $ pwd 111 | /home/użytkownik 112 | $ mkdir -p .qemu/ghostbsd 113 | $ fallocate -l $(( 8*1024*1024*1024 )) .qemu/ghostbsd/ghostbsd.img 114 | ``` 115 | 116 | Następnie uruchom GhostBSD: 117 | 118 | ```bash 119 | qemu-system-x86_64 -machine type=q35,accel=kvm \ 120 | -enable-kvm -cpu host -smp 2 -m 4096 \ 121 | -device virtio-net,netdev=vmnic -netdev user,id=vmnic,hostfwd=tcp::5222-:22 \ 122 | -vga std -soundhw hda -no-quit \ 123 | -drive format=raw,file=${HOME}/.qemu/ghostbsd/ghostbsd.img \ 124 | -drive format=raw,file=${HOME}/Downloads/ghostbsd.iso \ 125 | -boot menu=on 126 | ``` 127 | 128 | Gdy QEMU się uruchomi, naciśnij `esc` i wybierz `2`, aby uruchomić z ISO. 129 | 130 | Użyj narzędzia __Install GhostBSD__, aby zainstalować GhostBSD na obrazie dysku. 131 | 132 | Następnie uruchom ponownie QEMU, teraz usuń dwie ostatnie opcje z powyższego polecenia. 133 | 134 | Uwagi: 135 | 136 | * Opcja `hostfwd=` tworzy przekierowanie portu z portu `5222` hosta do portu `22` maszyny wirtualnej QEMU. 137 | * Niestety, opcje qemu-system-x86_64 dla tabletu USB nie działają; będziesz musiał nacisnąć Ctrl+Alt+g, aby zwolnić wskaźnik myszy z okna QEMU. 138 | * Aby przejść do pełnoekranowego trybu QEMU, naciśnij Ctrl+Alt+F. 139 | 140 | Aby uruchomić/zainstalować GhostBSD w trybie UEFI, najpierw zainstaluj [OVMF Open Virtual Machine Firmware](https://github.com/tianocore/tianocore.github.io/wiki/OVMF) na stronie hosta. Nazwa pakietu dla Fedora 32 to `edk2-ovmf`. 141 | 142 | Następnie dodaj te dwie opcje `qemu-system-x86_64`: 143 | ```bash 144 | -bios /usr/share/edk2/ovmf/OVMF_CODE.fd \ 145 | -smbios type=0,vendor=0vendor,version=0version,date=0date,release=0.0,uefi=on \ 146 | ``` 147 | 148 | ### Parallels 149 | 150 | Aby skonfigurować Parallels do uruchomienia GhostBSD: 151 | 152 | 1. Przejdź do **Hardware > Boot Order**. 153 | 2. Rozwiń **Advanced Settings**. 154 | 3. Ustaw **BIOS** na "EFI 64-bit". 155 | 4. W polu **Boot flags** wpisz `vm.bios.efi=1`. 156 | 157 | ![Screenshot](https://docs.01.org/clearlinux/latest/zh_CN/_images/parallels-07.png) 158 | 159 | ### Proxmox VE 160 | 161 | Aby uruchomić GhostBSD na Proxmox VE, skonfiguruj maszynę wirtualną z następującymi ustawieniami: 162 | 163 | - **Pamięć (Memory)**: 4 GB (nie może być dynamicznie alokowana) 164 | - **Procesory (Processors)**: 2 (1 socket, 2 rdzenie) 165 | - **BIOS**: OVMF (UEFI) 166 | - **Wyświetlacz (Display)**: Domyślny (VGA) 167 | - **Maszyna (Machine)**: q35 168 | - **Kontroler SATA (SATA Controller)**: VirtIO SATA do podłączenia wirtualnego dysku (na którym zainstalowany zostanie system) 169 | - **Napęd CD (CD Drive)**: GhostBSD ISO 170 | - **Dysk twardy (Hard Disk)**: Co najmniej 8 GB Raw 171 | - **Urządzenie sieciowe (Network Device)**: VirtIO 172 | 173 | Aby ustawić rozdzielczość, naciśnij F2 podczas uruchamiania, aby uzyskać dostęp do ustawień OVMF. Wybierz 'Device Manager > OVMF Platform Configuration > Change Preferred', zapisz i uruchom ponownie. 174 | 175 | ### VirtualBox 176 | 177 | Aby uruchomić GhostBSD w VirtualBox, postępuj zgodnie z poniższymi krokami: 178 | 179 | 1. **Instalacja VirtualBox**: 180 | - Pobierz i zainstaluj VirtualBox z menedżera pakietów systemu operacyjnego lub ze [strony internetowej VirtualBox](https://virtualbox.org). 181 | 182 | 2. **Utworzenie nowej maszyny wirtualnej**: 183 | - W VirtualBox Manager, wybierz **Tools > New**, aby utworzyć nową maszynę wirtualną z następującymi ustawieniami: 184 | - **Name and operating system**: 185 | - Nazwij maszynę wirtualną. 186 | - Ustaw **Type** na "FreeBSD". 187 | - Ustaw **Version** na "FreeBSD (64-bit)". 188 | - **Memory size**: 189 | - Ustaw **RAM** na co najmniej 4GB (4096MB). 190 | - **Hard disk**: 191 | - Domyślne ustawienia są zalecane. 192 | - **Hard disk file type**: 193 | - Domyślne ustawienia są zalecane. 194 | - **Storage on physical hard disk**: 195 | - Domyślne ustawienia są zalecane. 196 | - **File location and size**: 197 | - Domyślne ustawienia są odpowiednie, ale można zwiększyć maksymalny rozmiar wirtualnego dysku. 198 | 199 | 3. **Dostosowanie ustawień maszyny wirtualnej**: 200 | - Wybierz nową maszynę wirtualną w VirtualBox Manager i otwórz ekran ustawień. Skonfiguruj poniższe opcje: 201 | - **System > Motherboard**: 202 | - W sekcji **Extended Features** zaznacz "Enable EFI (special OSes only)". 203 | - **System > Processor**: 204 | - Ustaw **Processor(s)** na co najmniej 2 CPU. 205 | - **Display > Screen**: 206 | - Zmień **Graphics Controller** na VBoxSVGA. 207 | - **Storage**: 208 | - W sekcji **Storage Devices** wybierz Napęd Optyczny (ikona CD). 209 | - W sekcji **Attributes** kliknij ikonę CD, aby otworzyć menu rozwijane. 210 | - Wybierz "Choose a disk file..." i wskaż pobrany plik ISO GhostBSD. 211 | 212 | 4. **Uruchomienie maszyny wirtualnej**: 213 | - Kliknij "OK", aby zapisać zmiany. W VirtualBox Manager wybierz **Start**. System live GhostBSD uruchomi się w środowisku Mate. 214 | - Kliknij "Install GhostBSD", aby uruchomić instalator. 215 | - Po zakończeniu instalacji, uruchom ponownie lub wyłącz maszynę wirtualną i usuń ISO z napędu optycznego przed następnym uruchomieniem. -------------------------------------------------------------------------------- /contributor/code/python-guide.md: -------------------------------------------------------------------------------- 1 | # Python Development Guide 2 | 3 | This guide outlines the Python coding standards for GhostBSD projects. Following these standards ensures code consistency, maintainability, and compatibility with our development tools. 4 | 5 | ## Code Style Standards 6 | 7 | ### PEP 8 Compliance 8 | All Python code must follow PEP 8 standards with these specific configurations: 9 | 10 | - **Line length**: Maximum 120 characters 11 | - **Indentation**: 4 spaces (no tabs) 12 | - **Imports**: Organize in three groups separated by blank lines: 13 | 1. Standard library imports 14 | 2. Related third-party imports 15 | 3. Local application/library imports 16 | 17 | ### Naming Conventions 18 | - **Variables**: `snake_case` (e.g., `network_name`, `retry_count`) 19 | - **Functions**: `snake_case` (e.g., `connect_to_network()`, `get_available_networks()`) 20 | - **Methods**: `snake_case` (e.g., `self.setup_ui()`, `self._validate_input()`) 21 | - **Classes**: `PascalCase` (e.g., `NetworkManager`, `ConfigDialog`) 22 | - **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_ATTEMPTS`, `DEFAULT_TIMEOUT`) 23 | - **Private attributes**: Single leading underscore `_private_var` 24 | - **Protected attributes**: Double leading underscore `__protected_var` 25 | 26 | ### Code Formatting 27 | - **String quotes**: Use double quotes `"` for user-facing strings, single quotes `'` for internal strings 28 | - **Trailing commas**: Always use trailing commas in multi-line lists, tuples, and dictionaries 29 | - **Blank lines**: Two blank lines between top-level functions and classes, one blank line between methods 30 | 31 | ## Pylint Configuration 32 | 33 | Configure Pylint to match our standards by creating a `.pylintrc` file in your project root: 34 | 35 | ```ini 36 | [MASTER] 37 | extension-pkg-whitelist=gi 38 | 39 | [FORMAT] 40 | max-line-length=120 41 | indent-string=' ' 42 | 43 | [MESSAGES CONTROL] 44 | disable=missing-docstring, 45 | too-few-public-methods, 46 | import-error, 47 | no-member 48 | 49 | [DESIGN] 50 | max-args=8 51 | max-locals=20 52 | max-branches=15 53 | ``` 54 | 55 | ## Internationalization with Gettext 56 | 57 | All user-visible text must be internationalized using gettext. This ensures GhostBSD applications can be translated into multiple languages. 58 | 59 | ### Setting up Gettext 60 | 61 | Import and configure gettext at the top of your Python files following the GhostBSD pattern: 62 | 63 | ```python 64 | import gettext 65 | 66 | # Set up translation (replace 'your-app-name' with your application name) 67 | gettext.bindtextdomain('your-app-name', '/usr/local/share/locale') 68 | gettext.textdomain('your-app-name') 69 | _ = gettext.gettext 70 | ``` 71 | 72 | ### Marking Translatable Strings 73 | 74 | Wrap all user-visible strings with the `_()` function: 75 | 76 | ```python 77 | # Good - translatable 78 | error_message = _("Unable to connect to network") 79 | dialog.set_title(_("Network Settings")) 80 | button.set_label(_("Apply Changes")) 81 | 82 | # Bad - not translatable 83 | error_message = "Unable to connect to network" 84 | dialog.set_title("Network Settings") 85 | ``` 86 | 87 | ### String Formatting with Gettext 88 | 89 | Use format strings properly with translations: 90 | 91 | ```python 92 | # Good - proper formatting 93 | message = _("Connected to {network_name}").format(network_name=ssid) 94 | count_text = _("Found {count} networks").format(count=len(networks)) 95 | 96 | # Bad - formatting outside translation 97 | message = _("Connected to") + f" {ssid}" 98 | ``` 99 | 100 | ### Pluralization 101 | 102 | Handle plural forms correctly: 103 | 104 | ```python 105 | import ngettext 106 | 107 | # Proper pluralization 108 | count_message = ngettext( 109 | "Found {count} network", 110 | "Found {count} networks", 111 | network_count 112 | ).format(count=network_count) 113 | ``` 114 | 115 | ## Documentation Standards 116 | 117 | ### Docstrings 118 | Use Google-style docstrings for all public functions, classes, and modules: 119 | 120 | ```python 121 | def connect_to_network(ssid, password=None): 122 | """Connect to a wireless network. 123 | 124 | Args: 125 | ssid (str): The network SSID to connect to 126 | password (str, optional): Network password. Defaults to None. 127 | 128 | Returns: 129 | bool: True if connection successful, False otherwise 130 | 131 | Raises: 132 | NetworkError: If the network interface is not available 133 | """ 134 | pass 135 | ``` 136 | 137 | ### Type Hints 138 | Use type hints for function parameters and return values: 139 | 140 | ```python 141 | def get_available_networks() -> list[dict[str, str]]: 142 | """Get list of available wireless networks. 143 | 144 | Returns: 145 | List of dictionaries containing network information 146 | """ 147 | pass 148 | 149 | def connect_to_network(ssid: str, password: str | None = None) -> bool: 150 | """Connect to specified network.""" 151 | pass 152 | ``` 153 | 154 | ## Type Annotations 155 | 156 | Type annotations are required for all new code. Python 3.11+ provides modern syntax without importing from `typing`. 157 | 158 | ### Basic Types 159 | Use built-in types directly: 160 | 161 | ```python 162 | def process_config(name: str, port: int, enabled: bool) -> None: 163 | """Process configuration with basic types.""" 164 | pass 165 | 166 | def get_timeout() -> float: 167 | """Return timeout value in seconds.""" 168 | return 30.5 169 | ``` 170 | 171 | ### Collection Types 172 | Use built-in collection types directly: 173 | 174 | ```python 175 | def get_network_list() -> list[str]: 176 | """Return list of network names.""" 177 | return ["WiFi-1", "WiFi-2"] 178 | 179 | def get_network_config() -> dict[str, str]: 180 | """Return network configuration mapping.""" 181 | return {"ssid": "MyNetwork", "security": "WPA2"} 182 | 183 | def get_coordinates() -> tuple[int, int]: 184 | """Return x, y coordinates.""" 185 | return (100, 200) 186 | 187 | def get_unique_names() -> set[str]: 188 | """Return set of unique network names.""" 189 | return {"WiFi-1", "WiFi-2"} 190 | ``` 191 | 192 | ### Optional and Union Types 193 | Use modern union syntax with `|`: 194 | 195 | ```python 196 | def connect_with_password(password: str | None = None) -> bool: 197 | """Connect to network with optional password.""" 198 | if password is None: 199 | return connect_without_auth() 200 | return connect_with_auth(password) 201 | 202 | def parse_value(data: str | int) -> str: 203 | """Parse value that can be string or integer.""" 204 | return str(data) 205 | 206 | def get_config_value(key: str) -> str | int | bool: 207 | """Get configuration value of various types.""" 208 | pass 209 | ``` 210 | 211 | ### Class Annotations 212 | Annotate class attributes and methods: 213 | 214 | ```python 215 | class NetworkManager: 216 | """Network management class with type annotations.""" 217 | 218 | MAX_RETRIES: int = 3 # Class variable 219 | 220 | def __init__(self, interface: str) -> None: 221 | # Instance variables 222 | self.interface: str = interface 223 | self.connected: bool = False 224 | self.current_network: str | None = None 225 | self._retry_count: int = 0 226 | 227 | def get_networks(self) -> list[dict[str, str]]: 228 | """Get available networks.""" 229 | return [] 230 | 231 | def connect(self, ssid: str, password: str | None = None) -> bool: 232 | """Connect to specified network.""" 233 | self.current_network = ssid 234 | return True 235 | ``` 236 | 237 | ### Complex Collections 238 | Handle nested collections properly: 239 | 240 | ```python 241 | def get_network_details() -> dict[str, list[str]]: 242 | """Get network names mapped to their properties.""" 243 | return { 244 | "WiFi-1": ["WPA2", "5GHz", "Strong"], 245 | "WiFi-2": ["WPA3", "2.4GHz", "Weak"] 246 | } 247 | 248 | def process_connections( 249 | connections: list[tuple[str, bool]] 250 | ) -> dict[str, bool]: 251 | """Process list of connection tuples.""" 252 | return dict(connections) 253 | ``` 254 | 255 | ## Error Handling 256 | 257 | ### Exception Handling 258 | Use specific exception types and provide translatable error messages: 259 | 260 | ```python 261 | try: 262 | result = network_operation() 263 | except NetworkNotFoundError: 264 | error_dialog(_("Network not found. Please check the network name.")) 265 | except PermissionError: 266 | error_dialog(_("Permission denied. Please run as administrator.")) 267 | except Exception as e: 268 | logger.error("Unexpected error: %s", str(e)) 269 | error_dialog(_("An unexpected error occurred. Please try again.")) 270 | ``` 271 | 272 | ### Logging 273 | Use the standard logging module with appropriate levels: 274 | 275 | ```python 276 | import logging 277 | 278 | logger = logging.getLogger(__name__) 279 | 280 | def process_network_config(): 281 | logger.info(_("Starting network configuration")) 282 | try: 283 | # Process configuration 284 | logger.debug("Configuration data: %s", config_data) 285 | except ConfigError as e: 286 | logger.error(_("Configuration error: %s"), str(e)) 287 | raise 288 | ``` 289 | 290 | ## GTK3 Integration 291 | 292 | ### Widget Creation 293 | Follow consistent patterns when creating GTK widgets: 294 | 295 | ```python 296 | import gi 297 | gi.require_version('Gtk', '3.0') 298 | from gi.repository import Gtk 299 | 300 | class NetworkDialog(Gtk.Dialog): 301 | def __init__(self, parent=None): 302 | super().__init__( 303 | title=_("Network Settings"), 304 | parent=parent, 305 | modal=True 306 | ) 307 | 308 | # Add buttons with translatable labels 309 | self.add_button(_("Cancel"), Gtk.ResponseType.CANCEL) 310 | self.add_button(_("Apply"), Gtk.ResponseType.OK) 311 | 312 | self._setup_ui() 313 | 314 | def _setup_ui(self): 315 | """Set up the dialog user interface.""" 316 | pass 317 | ``` 318 | 319 | ### Signal Connections 320 | Use descriptive callback names and handle errors appropriately: 321 | 322 | ```python 323 | def _on_connect_button_clicked(self, button): 324 | """Handle connect button click event.""" 325 | try: 326 | ssid = self.ssid_entry.get_text() 327 | if not ssid: 328 | self._show_error(_("Please enter a network name")) 329 | return 330 | 331 | self._connect_to_network(ssid) 332 | except Exception as e: 333 | logger.error("Connection failed: %s", str(e)) 334 | self._show_error(_("Connection failed. Please try again.")) 335 | ``` 336 | 337 | ## Tools Integration 338 | 339 | ### IDE Recommendation 340 | PyCharm Community Edition is recommended for GhostBSD Python development. It provides excellent built-in code analysis, debugging capabilities, and seamless integration with the coding standards outlined above. 341 | 342 | Install PyCharm on GhostBSD: 343 | ```bash 344 | sudo pkg install pycharm-ce 345 | ``` 346 | 347 | PyCharm's default settings align well with these standards, providing automatic code formatting, linting, and error detection that matches our requirements. 348 | 349 | ### Pre-commit Hooks 350 | Consider setting up pre-commit hooks to automatically check code style: 351 | 352 | ```bash 353 | # Install pre-commit 354 | pip install pre-commit 355 | 356 | # Create .pre-commit-config.yaml 357 | pre-commit install 358 | ``` 359 | 360 | Following these standards helps maintain high code quality and ensures your contributions integrate smoothly with the existing GhostBSD codebase. -------------------------------------------------------------------------------- /_static/dark_mode.css: -------------------------------------------------------------------------------- 1 | /* Dark mode styles, applied only when body has the dark-mode class */ 2 | body.dark-mode { 3 | background-color: #252525; /* Slightly lighter dark gray */ 4 | color: #e0e0e0; /* Light gray text */ 5 | } 6 | 7 | body.dark-mode .wy-nav-top { 8 | background-color: #2b2b2b; /* Darker header */ 9 | } 10 | 11 | body.dark-mode .wy-nav-side { 12 | background-color: #2b2b2b; /* Dark sidebar */ 13 | } 14 | 15 | body.dark-mode .wy-menu-vertical a { 16 | color: #e0e0e0; /* Light sidebar links */ 17 | } 18 | 19 | body.dark-mode .wy-menu-vertical a:hover { 20 | background-color: #3c3c3c; /* Hover effect for general links */ 21 | } 22 | 23 | body.dark-mode .wy-nav-content { 24 | background-color: #252525; /* Match the body background */ 25 | } 26 | 27 | body.dark-mode h1, 28 | body.dark-mode h2, 29 | body.dark-mode h3, 30 | body.dark-mode h4, 31 | body.dark-mode h5, 32 | body.dark-mode h6 { 33 | color: #ffffff !important; /* White headings */ 34 | } 35 | 36 | /* More specific rules for content headings */ 37 | body.dark-mode .rst-content h1, 38 | body.dark-mode .rst-content h2, 39 | body.dark-mode .rst-content h3, 40 | body.dark-mode .rst-content h4, 41 | body.dark-mode .rst-content h5, 42 | body.dark-mode .rst-content h6 { 43 | color: #ffffff !important; /* White headings in content */ 44 | } 45 | 46 | /* Fix heading links that inherit link colors */ 47 | body.dark-mode .rst-content h1 a, 48 | body.dark-mode .rst-content h2 a, 49 | body.dark-mode .rst-content h3 a, 50 | body.dark-mode .rst-content h4 a, 51 | body.dark-mode .rst-content h5 a, 52 | body.dark-mode .rst-content h6 a { 53 | color: #ffffff !important; /* White heading links */ 54 | } 55 | 56 | /* Target the specific toc-backref links in headings */ 57 | body.dark-mode .rst-content a.toc-backref { 58 | color: #ffffff !important; /* White toc backref links */ 59 | } 60 | 61 | /* Target headerlink anchors in headings */ 62 | body.dark-mode .rst-content a.headerlink { 63 | color: #ffffff !important; /* White header anchor links */ 64 | } 65 | 66 | /* Even more specific for document section headings */ 67 | body.dark-mode .document h1, 68 | body.dark-mode .document h2, 69 | body.dark-mode .document h3, 70 | body.dark-mode .document h4, 71 | body.dark-mode .document h5, 72 | body.dark-mode .document h6 { 73 | color: #ffffff !important; /* White headings in document */ 74 | } 75 | 76 | body.dark-mode a { 77 | color: #4da8da; /* Light blue links */ 78 | } 79 | 80 | /* Only apply visited link color to content area, not navigation */ 81 | body.dark-mode .rst-content a:visited { 82 | color: #bb86fc; /* Light purple for visited links */ 83 | } 84 | 85 | body.dark-mode a:hover { 86 | color: #66b3ff; /* Lighter blue on hover */ 87 | } 88 | 89 | body.dark-mode pre { 90 | background-color: #2b2b2b; /* Dark code background */ 91 | color: #e0e0e0; /* Light code text */ 92 | border: 1px solid #3c3c3c; 93 | } 94 | 95 | /* Code blocks in dark mode */ 96 | /*.dark-mode .highlight {*/ 97 | /* background: #2b2b2b !important;*/ 98 | /* border: 1px solid #444 !important;*/ 99 | /*}*/ 100 | 101 | /* Inline code in dark mode */ 102 | .dark-mode .rst-content code.literal, 103 | .dark-mode .rst-content tt.literal { 104 | background: #404040 !important; 105 | color: #f8f8f2 !important; 106 | border: 1px solid #555 !important; 107 | padding: 2px 4px !important; 108 | } 109 | 110 | /* Syntax highlighting colors for dark mode */ 111 | .dark-mode .highlight .c { color: #75715e !important; } /* comments */ 112 | .dark-mode .highlight .k { color: #66d9ef !important; } /* keywords */ 113 | .dark-mode .highlight .s { color: #e6db74 !important; } /* strings */ 114 | .dark-mode .highlight .mi { color: #ae81ff !important; } /* numbers */ 115 | .dark-mode .highlight .n { color: #f8f8f2 !important; } /* names */ 116 | .dark-mode .highlight .nb { color: #f92672 !important; } /* builtins */ 117 | .dark-mode .highlight .nf { color: #a6e22e !important; } /* functions */ 118 | .dark-mode .highlight .o { color: #f92672 !important; } /* operators */ 119 | .dark-mode .highlight .p { color: #f8f8f2 !important; } /* punctuation */ 120 | .dark-mode .highlight .nn { color: #66d9ef !important; } /* imports/namespaces */ 121 | .dark-mode .highlight .kn { color: #f92672 !important; } /* import keywords */ 122 | .dark-mode .highlight .na { color: #a6e22e !important; } /* attribute names */ 123 | .dark-mode .highlight .nc { color: #a6e22e !important; } /* class names */ 124 | .dark-mode .highlight .nd { color: #a6e22e !important; } /* decorators */ 125 | .dark-mode .highlight .ne { color: #a6e22e !important; } /* exceptions */ 126 | .dark-mode .highlight .ni { color: #f92672 !important; } /* name indicators */ 127 | .dark-mode .highlight .nl { color: #f92672 !important; } /* name labels */ 128 | .dark-mode .highlight .nt { color: #f92672 !important; } /* name tags */ 129 | .dark-mode .highlight .nv { color: #f8f8f2 !important; } /* name variables */ 130 | .dark-mode .highlight .ow { color: #f92672 !important; } /* operator words */ 131 | .dark-mode .highlight .w { color: #f8f8f2 !important; } /* whitespace */ 132 | .dark-mode .highlight .mf { color: #ae81ff !important; } /* numbers float */ 133 | .dark-mode .highlight .mh { color: #ae81ff !important; } /* numbers hex */ 134 | .dark-mode .highlight .mo { color: #ae81ff !important; } /* numbers octal */ 135 | .dark-mode .highlight .sb { color: #e6db74 !important; } /* string backtick */ 136 | .dark-mode .highlight .sc { color: #e6db74 !important; } /* string char */ 137 | .dark-mode .highlight .sd { color: #e6db74 !important; } /* string doc */ 138 | .dark-mode .highlight .s2 { color: #e6db74 !important; } /* string double */ 139 | .dark-mode .highlight .se { color: #ae81ff !important; } /* string escape */ 140 | .dark-mode .highlight .sh { color: #e6db74 !important; } /* string heredoc */ 141 | .dark-mode .highlight .si { color: #e6db74 !important; } /* string interpol */ 142 | .dark-mode .highlight .sx { color: #e6db74 !important; } /* string other */ 143 | .dark-mode .highlight .sr { color: #e6db74 !important; } /* string regex */ 144 | .dark-mode .highlight .s1 { color: #e6db74 !important; } /* string single */ 145 | .dark-mode .highlight .ss { color: #e6db74 !important; } /* string symbol */ 146 | 147 | 148 | /* Code block container */ 149 | /*.dark-mode .rst-content .highlight {*/ 150 | /* margin: 1em 0 !important;*/ 151 | /*}*/ 152 | 153 | 154 | /* Optional: Style the toggle button */ 155 | button { 156 | padding: 8px 16px; 157 | background-color: #4da8da; 158 | color: white; 159 | border: none; 160 | border-radius: 4px; 161 | cursor: pointer; 162 | } 163 | 164 | button:hover { 165 | background-color: #66b3ff; 166 | } 167 | 168 | body.dark-mode button { 169 | background-color: #2b2b2b; 170 | color: #e0e0e0; 171 | } 172 | 173 | body.dark-mode button:hover { 174 | background-color: #3c3c3c; 175 | } 176 | 177 | /* Ensure proper layout in wy-breadcrumbs */ 178 | .wy-breadcrumbs { 179 | position: relative; 180 | padding: 0 10px; 181 | overflow: hidden; /* Contain floated elements */ 182 | white-space: nowrap; /* Prevent wrapping */ 183 | } 184 | 185 | /* Style
  • elements to stay inline */ 186 | .wy-breadcrumbs li { 187 | display: inline-block; 188 | margin-right: 5px; 189 | vertical-align: middle; /* Align breadcrumb items */ 190 | } 191 | 192 | /* Style wy-breadcrumbs-aside to keep "View page source" on the right */ 193 | .wy-breadcrumbs-aside { 194 | float: right; /* Matches theme's default behavior */ 195 | display: inline-block; 196 | margin-left: 10px; /* Space from button */ 197 | } 198 | 199 | /* Ensure "View page source" aligns properly */ 200 | .wy-breadcrumbs-aside a { 201 | display: inline-block; 202 | vertical-align: middle; 203 | } 204 | 205 | /* Style the button directly in wy-breadcrumbs to stay on the right */ 206 | .wy-breadcrumbs button { 207 | float: right; /* Pin to the right */ 208 | margin-left: 10px; /* Space from breadcrumb text */ 209 | margin-right: 10px; /* Space before "View page source" */ 210 | vertical-align: middle; /* Align with other items */ 211 | } 212 | 213 | /* Keep GhostBSD white in both modes */ 214 | .wy-side-nav-search .icon.icon-home:not([aria-label="Home"]) { 215 | color: #ffffff; /* White in light mode */ 216 | } 217 | 218 | body.dark-mode .wy-side-nav-search .icon.icon-home:not([aria-label="Home"]) { 219 | color: #ffffff; /* White in dark mode */ 220 | } 221 | 222 | /* Fix white background of .toctree-l1.current in dark mode */ 223 | body.dark-mode .wy-menu-vertical .toctree-l1.current { 224 | background-color: #3c3c3c; /* Slightly lighter than sidebar */ 225 | } 226 | 227 | /* Darken background of in dark mode */ 228 | body.dark-mode .wy-menu-vertical a.reference.internal.current { 229 | background-color: #333333; /* Darker than #3c3c3c */ 230 | } 231 | 232 | /* Ensure .toctree-l2 fills the li and darkens on hover */ 233 | .wy-menu-vertical .toctree-l2 a { 234 | display: block; /* Ensure it fills the li */ 235 | } 236 | 237 | body.dark-mode .wy-menu-vertical .toctree-l2 a:hover { 238 | background-color: #2a2a2a !important; /* Darker than #3c3c3c, override all */ 239 | } 240 | 241 | /* Ensure in sidebar fills its parent
  • */ 242 | .wy-menu-vertical .toctree-l1 a { 243 | display: block; /* Ensure it fills the li */ 244 | } 245 | 246 | /* Ensure in toctree-l3 fills its parent
  • */ 247 | .wy-menu-vertical .toctree-l3 a { 248 | display: block; /* Ensure it fills the li */ 249 | } 250 | 251 | /* Darken inside .toctree-l1.current[aria-expanded="true"] at all times */ 252 | body.dark-mode .wy-menu-vertical .toctree-l1.current[aria-expanded="true"] a[href="#"] { 253 | background-color: #2b2b2b; /* Darker than #3c3c3c, constant background */ 254 | } 255 | 256 | /* Highly specific override for .toctree-l2.current in dark mode */ 257 | body.dark-mode .wy-nav-side .wy-menu.wy-menu-vertical ul li.current.toctree-l2 { 258 | background-color: #3c3c3c !important; /* Reordered classes for specificity */ 259 | } 260 | 261 | /* Ensure li.toctree-l2.current has the correct background in dark mode */ 262 | body.dark-mode .wy-menu-vertical li.toctree-l2.current { 263 | background-color: #3c3c3c !important; 264 | } 265 | 266 | /* Ensure the inside li.toctree-l2.current does not override the background */ 267 | body.dark-mode .wy-menu-vertical li.toctree-l2.current a { 268 | background-color: transparent !important; 269 | } 270 | 271 | /* Ensure nested