## 1. Project Overview & Quickstart (TheAssassin/BUILD) # BUILD The official build framework for the Armbian Linux distribution. This repository contains the complete toolchain and scripts required to compile custom OS images from source, including kernel configuration, U-Boot handling, and board-specific tweaks for various ARM and ARM64 single-board computers. ### Repository Details - **Repository:** [TheAssassin/BUILD](https://github.com/TheAssassin/BUILD) - **GitHub Stars:** ⭐ 5,342 - **Primary Language:** Shell *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (TheAssassin/docs) ## File: README.md # hello Documentation This repository builds the [documentation](https://hellosystem.github.io/docs/) for hello. It uses Sphinx, recommonmark, and GitHub Actions to produce documentation from the Markdown source files in this repository. * https://stackoverflow.com/a/62967771 * https://recommonmark.readthedocs.io/en/latest/ ## Local development server Use a local development server that regenerates the output whenever the input changes: ``` sudo pkg install -y py37-pip pip-3.7 install -r requirements.txt export GITHUB_REPOSITORY="helloSystem/docs" export PATH=~/.local/bin/:$PATH make watch ``` Now open http://127.0.0.1:8000 in a web browser. It will be regenerated and refreshed whenever one of the input files changes. --- ## File: index.md ```eval_rst .. image:: https://raw.githubusercontent.com/helloSystem/hello/1d1e69be8a689c5e0a176df821c14f0b49b241a4/branding/hello_variation.svg :align: center :width: 300px ``` ```eval_rst .. centered:: Willkommen • Welcome • 欢迎 • Bienvenue • Benvenuto • Bienvenido • ようこそ • Mabuhay • Välkommen • أهلا وسهلا • Добро пожаловать • Merhaba • Bonvenon • 歡迎光臨 ``` # hello __hello__ (also known as __helloSystem__) is a desktop system for creators with focus on simplicity, elegance, and usability. Its design follows the "Less, but better" philosophy. It is intended as a system for "mere mortals", welcoming to switchers from the Mac. [FreeBSD](https://www.freebsd.org/) is used as the core operating system. Please refer to [https://github.com/helloSystem/hello](https://github.com/helloSystem/hello) if you would like to learn more about the ideas and principles behind hello. ```eval_rst .. toctree:: :hidden: :maxdepth: 2 user/index developer/index ``` --- ## File: requirements.txt wheel sphinx>=3.3.0 sphinx_rtd_theme sphinx-autobuild sphinx_git #sphinx-reredirects sphinxext-rediraffe # will only work once a new release is made after sphinx-rtd-theme 0.5.0 sphinx-last-updated-by-git recommonmark --- ## File: developer/acknowledgements.md # Acknowledgements Grateful acknowledgement is made to the following persons and organizations. Mentions roughly in the order of first involvement with the project. ## FreeBSD project [https://www.freebsd.org/](https://www.freebsd.org/) * Providing the underlying operating system ## FreeBSD port maintainers As listed on [https://www.freshports.org/](https://www.freshports.org/) * Providing end user applications ## Simon Peter __[probonopd](https://github.com/probonopd)__ @probonopd on twitter * Founded the project * Acting as the main developer ## Joe Maloney __[pkgdemon](https://github.com/pkgdemon)__ @FuryBSD on twitter * Originally wrote the tools to create Live ISOs for FuryBSD ## FreeBSD Foundation [https://www.freebsdfoundation.org/](https://www.freebsdfoundation.org/) * Gave permission to use the trademarks in the 'Install FreeBSD' utility ## Sławomir Wojciech Wojtczak __[vermaden](https://github.com/vermaden)__ @vermaden on twitter * Provided helpful feedback and configuration advice * Configuration for tap to click and two-finger scrolling for Synaptics and Elan touchpads ## Reven Martin __[rekols](https://github.com/rekols)__ @revenmartin on twitter * Originally wrote Panda Status Bar, which the hello Menu is based on * Originally wrote Cyber Dock, which the hello Dock is based on ## Ale Rimoldi __[aoloe](https://github.com/aoloe)__ @a_l_e on twitter * Implemented Action Search (search through menubar) ## Antony jr __[antony-jr](https://github.com/antony-jr)__ @antonyjr0 on twitter * Put Search field for Action Search in menubar * Integrated of 'System' menu into menubar ## Keshav Bhatt __[keshavbhatt](https://github.com/keshavbhatt)__ @keshavmail68 on twitter * Helped making 'System' menu submenus clickable ## @FreeBSDHelp on twitter * Reached out to FreeBSD kernel developers ## TheAssassin __[TheAssassin](https://github.com/TheAssassin)__ * Improved documentation by providing Sphinx evangelism and ReStructuredText help --- ## File: developer/building.md # Building the Live ISO helloSystem get assembled from upstream FreeBSD components, components in the FreeBSD packages system, and custom components from the helloSystem repositories. helloSystem is not a derivative (fork) of FreeBSD (like e.g., GhostBSD), but strives to be "real FreeBSD" as far as possible. Hence, helloSystem does not build all source code, but relies on binaries provided by FreeBSD wherever possible. helloSystem is distributed as an installable Live ISO file. This file gets built by the [hello Live ISO builder](https://github.com/helloSystem/ISO). Continuous builds of the ISO get produced automatically on a continuous integration (CI) system for each git commit. However, it is also possible to build the ISO locally, which is especially handy for testing and development. ## System requirements for building * A FreeBSD or helloSystem installed on the computer. The FreeBSD version needs to match the FreeBSD version of the helloSystem ISO being built (e.g., `12.2-RELEASE`) * 2 GHz dual core processor * 4 GiB RAM (system memory) * 50 GB of hard-drive space * Either a CD-RW/DVD-RW drive or a USB port for writing the Live media * A fast internet connection ## Building the Live ISO ``` git clone https://github.com/helloSystem/ISO cd ISO sudo ./build.sh hello ``` The resulting Live ISO will be located at `/usr/local/furybsd/iso/`. ## Writing Live Media to USB drive ``` sudo dd if=/usr/local/furybsd/iso/FuryBSD-12.1-XFCE.iso of=/dev/daX bs=4m status=progress ``` Replace `daX` with the respective device name. ``` .. warning:: This will overwrite the entire contents of the selected device. Take extra caution when determining the device name. This operation cannot be undone. ``` For end users, there is the __Create Live Media__ application that can conveniently download and write Live Media with a graphical user interface. ## Burning Live Media to DVD You can use the `cdrecord` command line tool to burn Live Media to DVD. ``` pkg install cdrtools cdrecord /usr/local/furybsd/iso/.iso ``` ## Customizing the Live ISO helloSystem is built in a way that makes it trivially easy to apply your own changes to it. ### Different desktop environments Simply replace `hello` with the name of one of the supported desktop environments, such as * cinnamon * gnome * kde * openbox * xfce While the resulting image will be built on the same infrastructure, those will not be helloSystem builds and are not supported by the project. Still, the community may find them useful. ### Customizing the set of packages To add or remove packages, edit `settings/packages.` and rebuild the image. Substitute `` with `hello` or one of the desktop environments mentioned above. ### Customizing configuration Configuration is applied using _transient packages_ that get generated on-the-fly from the contents of the `overlays/` directory. * Overlays for the boot disk are stored in `overlays/boot` * Overlays for the initial ramdisk are stored in `overlays/ramdisk` * Overlays for the main filesystem are stored in `overlays/uzip//files/`. Note that to be included in a build, the overlay called `` must be listed in `settings/overlays.`. Substitute `` with `hello` or one of the desktop environments mentioned above. For example, a file that is supposed to appear in `/usr/local/bin/app` on the main filesystem could be stored in `overlays/uzip/hello/files/usr/local/bin/app`. ### Customizing the build script If a file called `settings/script.` exists, then it will be executed during the build. Substitute `` with `hello` or one of the desktop environments mentioned above. For building helloSystem, `settings/script.hello` performs actions such as installing applications that are not coming from FreeBSD packages, setting the wallpaper, installing fonts that are not coming from FreeBSD, and so on. All desktop-specific build steps should go into this file. --- ## File: developer/contact.md # Contact Developers chat at `#FuryBSD` on `irc.freenode.net`. Since we are working in different timezones, do not expect immediate answers. It is best to stay connected for at least a couple of days or so. --- ## File: developer/contributing.md # Contributing If you have found this page, chances are that you are considering to to contribute to this project. Awesome! This is a small, purely volunteer-driven project, so your contributions are _highly_ welcome. ## How to get started? * Download the pre-alpha Live ISO from https://github.com/helloSystem/ISO/releases/tag/continuous-hello * Look through the GitHub Issues sections of the projects within https://github.com/helloSystem/ * A great way to get started is to comment on some GitHub issues. Also feel free to open new ones. We use GitHub Issues as a means of discussion and keeping track of everything, so don't hesitate to use them. General topics not related to any particular component go to https://github.com/helloSystem/hello/issues * Especially have a look at issues marked with . Here your contributions would be especially helpful, but of course your contibutions to other tickets are more than welcome, too * There is a liberal amount of `FIXME` and `TODO` in the source code. Reducing the number of those is always highly welcome ## Our project values * Please see https://github.com/helloSystem/hello for the general philosophy of the project * Always keep in mind that our philosophy is "simple > complicated", "less, but better" * We prefer small pull requests that change one thing each, rather than large ones that do many things at once * Please avoid complex code structures that require deep C++ knowledge (e.g., avoid subclassing, pointer arithmetic,... where possible) * We appreciate code with comments that explain why we are doing something * Our policy is to merge PRs liberally but roll back changes that cause breakage quickly. `master` must always build and not crash ## Areas we especially need help with Here is what we need help with: [Issues flagged with help-wanted](https://github.com/search?q=org%3AhelloSystem+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22), and of course other contributions are also welcome. Maybe you'd like to look into one of these: [Issues flagged with good-first-issue](https://github.com/search?q=org%3AhelloSystem+is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22&type=). ### FreeBSD related topics Skills/resources we don't currently have and would highly appreciate help with |Skillset needed|Topic|Status|Rationale|Contact| |---|---|---|---|---| |FreeBSD kernel|Overhaul/bugfixing for unionfs.ko to create a read-write root filesystem|Idea|Save time and RAM by not having to copy the whole root filesystem to RAM|probonopd| |OpenZFS|A way to combine read-only (Live ISO) with read-write (ramdisk) to create a read-write root filesystem|Idea|Save time and RAM by not having to copy the whole root filesystem to RAM|probonopd| |FreeBSD kernel, graphics|Zero-text bootsplash that shows a boot animation and hides all text unless verbosity is explicitly requested|Idea|Put together "appliance" style systems that are not frightening non-technical users|probonopd| |FreeBSD build system|Kernel-related packages built for each FreeBSD version ([details](https://github.com/furybsd/furybsd-livecd/issues/241))|idea|Xorg fails on 12.2-RELEASE|probonopd| |FreeBSD Linuxulator|Make it possible for Linux applications to use FreeBSD D-Bus|Idea|Have Linux applications to use the [global menu](https://github.com/helloSystem/Menu) that is running on FreeBSD|probonopd| |FreeBSD kernel, Golang|Enable Go-based FUSE filesystems for FreeBSD ([issue](https://github.com/jacobsa/fuse/issues/91))|Idea|Packages that are images rather than archives: Experiment with [distr1](http://distr1.org/) concepts on FreeBSD|probonopd| |Qt, OpenZFS|ZFS snapshot, clone integration into the file manager|Idea|Expose the power of ZFS to non-technical users|probonopd| ### Qt related topics |Skillset needed|Topic|Status|Rationale|Contact| |---|---|---|---|---| |Qt|Improve the Filer (file manager)||Please see https://github.com/helloSystem/Filer/issues|probonopd| |Qt|Improve the Menu (global menu bar)||Please see https://github.com/helloSystem/Menu/issues|probonopd| --- ## File: developer/distributions.md # Note to distributions helloSystem is designed, developed, and tested as an integrated operating system. It is not a desktop environment designed to run on various operating systems or distributions. Focusing on building one coherent operating system greatly simplifies the code, the development and testing process, and ultimately increases quality. __Please do not try to include helloSystem in third-party distributions.__ While you are free to use components from helloSystem for your own projects as far as their respective licenses permit, please be aware that we may not always be interested in contributions that increase portability, especially if they would incrase complexity significantly. __Please do not call your derivatives "hello" or "helloSystem"__. In order to keep support and maintenance burden low, please give clearly distinguishable names to your derivatives. Please do not hesitate to contact the team if you have questions regarding this policy. --- ## File: developer/index.md # Developer Guide ```eval_rst .. toctree:: :maxdepth: 2 :glob: contributing building distributions acknowledgements contact ``` --- ## File: user/components.md # Getting to know the system helloSystem conststs of the following key components, each of which are described in this section: ```eval_rst .. toctree:: :maxdepth: 2 :glob: components/* ``` --- ## File: user/feedback.md # Providing feedback ## Sharing your experience If you would share your experience with helloSystem on twitter, use the [`#helloSystem` hashtag](https://twitter.com/hashtag/helloSystem). ## Discussing ideas and wishlist items Please check [https://github.com/helloSystem/hello](https://github.com/helloSystem/hello) fist, including the [wiki](https://github.com/helloSystem/hello/wiki). Feel free to discuss ideas and wishlist items at [https://github.com/helloSystem/hello/issues](https://github.com/helloSystem/hello/issues), but please do keep in mind that in order to achieve the intended goal of simplicity, the team needs to say "no" to most wishlist items that do not further that goal. --- ## File: user/getting-started.md # Getting started ## Status hello is currently being developed. It is not yet available for general use, but advanced users can try out continuous builds of pre-alpha ISO images that can be booted from DVD or USB storage media. ## System requirements * 2 GHz dual core Intel/ARM 64-bit processor * 4 GiB RAM (system memory for physical and viritualized installs) * VGA capable of 1024x768 screen resolution * Either a CD/DVD drive or a USB port for booting the installer media In the future, there may also be builds for other processor architectures. We would like to bring down the RAM requirement considerably. Please refer to [FreeBSD Hardware Compatibility](https://www.freebsd.org/doc/en_US.ISO8859-1/books/faq/hardware.html) for more information on individual components. ### Tested hardware hello 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. * Acer Revo RL85 * Dell Inc. OptiPlex 780 ### Tested virtualization environments * VirtualBox host (on FreeBSD) * VMware host (on Windows) ## Downloading Continuous builds of pre-alpha ISO images are available for download [here](https://github.com/helloSystem/ISO/releases/tag/continuous-hello). ```eval_rst important:: Images get built automatically whenever source code is committed. Not every build is tested. ``` --- ## File: user/index.md # User Guide ```eval_rst .. toctree:: :maxdepth: 2 :glob: getting-started components troubleshooting feedback ``` --- ## File: user/troubleshooting.md # Troubleshooting ## Known issues * __Boot stalls during `Replicate system image to swap-based memdisk`__: This build of the ISO is damaged. Please wait for another continuous build to appear and try again. * __Boots to a non-graphical `login:` prompt__: Your grahpics hardware was not detected properly. Please try on another machine. ## Getting help Developers chat at `#FuryBSD` on `irc.freenode.net`. Since we are working in different timezones, do not expect immediate answers. It is best to stay connected for at least a couple of days or so. ## Reporting bugs Please search [https://github.com/helloSystem/ISO/issues](https://github.com/helloSystem/ISO/issues) for known issues. Feel free to add to existing issues or to open new issues there. --- ## File: user/components/applications.md # Applications helloSystem comes with the following applications, each of which are described in this section: ```eval_rst .. toctree:: :maxdepth: 2 :glob: applications/* ``` --- ## File: user/components/autostart.md # Autostart The __Autostart__ mechanism provides an easy way to automatically start applications whenever the computer is started (to be precise, when a user is logged into a graphical desktop session). Applications can be either `.app` bundles or `.AppDir` directories. * __System-wide autostart__: Place applications (or symlinks to applications) into the `/Applications` folder to have them started for all users of the computer * __Per-user autostart__: Place applications (or symlinks to applications) into the `~/Applications` folder (in your home folder) to have them started for all users of the computer. You can create the folder if it does not exist yet The `launch` command is invoked for each of those applications and launches the applications. --- ## File: user/components/preferences.md # Preferences helloSystem comes with the following preferences applications, each of which are described in this section: ```eval_rst .. toctree:: :maxdepth: 2 :glob: preferences/* ``` --- ## File: user/components/system.md # System components helloSystem comes with the following system components, each of which are described in this section: ```eval_rst .. toctree:: :maxdepth: 2 :glob: system/* ``` --- ## File: user/components/utilities.md # Utilities helloSystem comes with the following utilities, each of which are described in this section: ```eval_rst .. toctree:: :maxdepth: 2 :glob: utilities/* ``` --- ## File: user/components/windows.md # Windows helloSystem provides a graphical desktop experience that should be familiar to users of existing desktop operating systems. ## Traffic lights Windows contain three buttons, called "traffic lights": * __Red__: Click this button to close the window * __Yellow__: Click this button to hide (minimize) the window. To make the window appear again, click on its icon in the Dock, or select "Unhide all" from the System menu * __Green__: Click this button to make the window use the full screen real estate available (maximize). Click this button again to resize the window to its previous size ## Resizing windows Place the mouse cursor in any edge of the window. The cursor will change. Click and drag the mouse to resize the window. Alternatively, click in the window title with the right-hand mouse button and select "Resize" from the menu, then drag the mouse to resize the window. --- ## File: user/components/applications/chromium.md # Chromium Chromium is the web browser that comes with helloSystem by default. Upon first start of the Chromium browser, the following extensions are automatically installed from [https://chrome.google.com/webstore/](https://chrome.google.com/webstore/) to increase privacy and convenience: * __I don't care about cookies__: Tries to remove annoying cookie popups automatically. Visit [https://www.i-dont-care-about-cookies.eu](https://www.i-dont-care-about-cookies.eu) to learn more about this extension. Deactivate or uninstall this extension if you would like to see cookie popups * __uBlock Origin__: Tries to block unwanted adversising and tracking. Visit [https://github.com/gorhill/uBlock](https://github.com/gorhill/uBlock) to learn more about this extension. Deactivate or uninstall this extension if you would like to see adversising and allow trackers to track you. You can uninstall those extensions at any time from within Chromomium. If wou would like Chromium not to install those extensions from the Chrome Web Store in the first place, remove the files in `/usr/local/share/chromium/extensions/*.json` prior to launching Chromium for the first time. --- ## File: user/components/preferences/boot-environments.md # Boot Environments _Boot Environments_ are bootable clones of snapshots of the working system. Boot Environments allow you to create a safe failback Boot Environmnent before upgrading or making major changes to the system. Other applications may create Boot Environmnents automatically before performing critical operations such as major operating system upgrades. ``` .. warning:: Boot Environments by default do not cover all locations, such as `/home` where your personal data is usually stored. ``` The __Boot Environments__ preferences application lets you view, create, remove, mount, and boot into Boot Environments. ``` .. note:: Boot Environments functionality cannot be used when the system is running from Live media. It can only be used when the system has been installed to a disk. ``` ## Viewing Boot Environments Open the __Boot Environments__ preferences application. If you have a user password set, you will be asked to enter your credentials. Only users in whe administrative group (`wheel`) can use the Boot Environments application by default. You will see the available Boot Environments. ## Creating Boot Environments To create a new Boot Environment, click "New..." and enter a name for the new Boot Environment. ## Removing Boot Environments Select a Boot Environment by clicking on it, and then press "Remove". Note that you cannot remove the currently active Boot Environment. ## Mounting Boot Environments You can make available, or "mount", existing Boot Environments, e.g., in order to inspect them or to copy files from there. To do this, select a Boot Environment by clicking on it, and then press "Mount". Note that you cannot mout the currently active Boot Environment since it is already mounted at `/`. The selected Boot Environment will be mounted, and a Filer window will be opened at the mountpoint of the Boot Environment. ## Booting into a Boot Environment Activate a Boot Environment by checking its checkbox, and then press "Restart...". The computer will restart into the selected Boot Environment. ## More Information Advanced users can use the `bectl` command on the command line, which the __Boot Environments__ preferences application is using under the hood. For more information regarding Boot Environments, please refer to the [ZFS Boot Environments](https://bsd-pl.org/assets/talks/2018-07-30_1_S%C5%82awomir-Wojciech-Wojtczak_ZFS-Boot-Environments.pdf) presentation by Sławomir Wojciech Wojtczak. --- ## File: user/components/preferences/desktop.md # Desktop The __Desktop__ preferences application allows you do customize the behavior of your computer's desktop. ## Background In this section of the __Desktop__ preferences application, you can select a background color and an optional background image. If an image is selected, you can choose how it should be scaled on the screen. ## Label Text In this section of the __Desktop__ preferences application, you can select a font and color for the text beneath icons on the desktop. ## Advanced Under the __advanced__ tab of the __Desktop__ preferences application, advanced users can adjust additional aspects of the behavior of the desktop. Most users should leave the defaults. This tab may go away in a future version. --- ## File: user/components/preferences/shortcuts.md # Shortcut Keys The __Shortcut Keys__ preferences application lets you view and edit system-wide keyboard shortcuts. A __shortcut__ is a key or key combination you can press to invoke a defined action on your computer. Shortcuts can be defined by applications (per-application shortcuts), or can affect the whole system (system-wide shortcuts). ``` .. note:: The Shortcut Keys preferences application lets you view and edit system-wide keyboard shortcuts only, not per-application shortcuts. Some applications contain similar functionality inside the respective application to view and edit per-application keyboard shortcuts. ``` ## Default shortcuts Open the __Shortcut Keys__ preferences application to view the default system-wide shortcuts. Notable default shortcuts include: * Press __Alt+Space__ to __search in the Menu__ (e.g., to launch applications or to execute commands in the frontmost application) * Press __Ctrl+Alt+Esc__ and click on an application window to __forcefully quit an application__ that is malfunctioning * Press __Alt+Shift+3__ or the __PrtScn__ key on your keyboard to __take a screenshot__ This list is not exhaustive. ## Viewing shortcuts For a complete list of system-wide shortcuts, please open the __Shortcut Keys__ preferences application to view the default shortcuts. ## Editing shortcuts Use the buttons in the __Shortcut Keys__ preferences application to add, remove, and modify system-wide shortcuts. --- ## File: user/components/system/dock.md # Dock The __Dock__ is a quick way to launch the most commonly used applications, and a way to see which applications are running at a glance. It typically sits at the bottom of the screen. ## Launching applications To launch an application, click on it in the Dock. ## Seeing running applications Running applications are marked with a dot below the application icon in the Dock. ## Keeping applications in the Dock To keep an application in the Dock even if it is not running, click on its icon in the Dock with the right mouse key, and select "Pin" from the context menu. --- ## File: user/components/system/filer.md # Filer __Filer__ is the application that you can use to manage objects like files, folders, and applications on your computer. Filer can perform typical tasks of a file manager: * Open files and folders * Create, move, and delete files and folders In helloSystem, many tasks are done in the Filer that would require extra tools in other operating systems. For example, you can use the Filer to * Launch applications (instead of using a dedicated launcher) * Make applications available to the system (instead of using a package manager or compiling from source) * Remove applications (instead of using a package manager) * Accessing files on remote computers (instead of using a dedicated application that can access files over ssh/sftp) ## Launching applications To launch an application, double-click it in Filer. In case you double-click on a binary that is lacking the execute permission, a dialog will ask you whether you would like to make the binary executable. ## Making applications available to the system Applications for helloSystem typically come as application bundles. An application bundle looks like a file but is actually stored as a directory on disk. To make an application available to the system, simply move or copy it to one of the well-known locations for applications, such as `/Applications` for system-wide applications, or `~/Applications` (in your home directory) for per-user applications. In addition to applications specifically offered for helloSystem, advanced users can use the tools provided by FreeBSD to compile applications from the ports tree, and/or to install FreeBSD packages. ## Removing applications To remove an application from the system, move it to the Trash. ## Accessing files on remote computers Computers on the local area network that are offering access via SFTP are automatically discovered and are shown in the "Network" area of Filer. Double-click on a network directory to access it. You will be asked to provide valid credentials (username, password) of an account on the remote computer. For this to work, computers need to provide SFTP services and announce them over dns-sd (Zeroconf, Bonjour). It is also possible to access files on computers that are not on the local area network. To do so, enter `sftp://hostname.tld` in the address bar of Filer and press the Enter key. --- ## File: user/components/system/launch.md # launch ```eval_rst .. epigraph:: "It’s not just what it looks like and feels like. Design is how it works." -- Steve Jobs ``` The `launch` command is used to launch graphical applications on helloSystem. When you select an application from the [Menu](menu.md) or the [Dock](dock.md), then the `launch` command is invoked to actually launch the application. ```eval_rst .. hint:: As an end user who is using the graphical user interface exclusively, you will not need to interact with the `launch` command directly and can skip this section. ``` ## Background On UNIX systems, applications are typically launched by entering the name of the executable file, which is searched in a fixed list of directories determined by the `$PATH` environment variable. Many graphical desktop environments use `.desktop` files to integrate applications with the system. While this has traditionally worked well for installed applications, it does not work well for dynamically changing applications that are moved in the filesystem, such as `.app` bundles or `.AppDir` directories. Also, it does not handle mutliple versions of the same application gracefully. Hence, helloSystem uses the `launch` command to launch graphical applications. This has the following advantages: * You do not need to know the path to the application to be launched, even if the applciation is not on the `$PATH` * If something goes wrong and the application cannot be launched, then a graphical error message will be shown on the screen * If multiple versions of an application are available on the system, the most recent one will be launched automatically (unless specified otherwise by the user) __(to be implemented)__ ## Using the `launch` command Whenever possible, graphical applications should be launched through the `launch` command on helloSystem. There are several ways in which the `launch` command can be invoked: * `launch /Applications/Filer.app` * `launch Filer.app` * `launch Filer` --- ## File: user/components/system/menu.md # Menu The menu bar at the top of the screen lets you perform, among others, the following functions: * Get information about your computer * Hide and unhide windows * Launch applications * Shut down your computer * Search in application menus * See date and time ## Getting computer information Select "About This Computer" from the "System" menu. ## Managing windows Select "Hide all" to minimize all windows to the Dock. Select "Unhide all" to get all windows back on screen. ## Launching applications Select an application from "Applications", "Utilities", or "Preferences" in the "Applications" menu. A quicker way to launch an application is to press Alt+Space, enter a few characters of the application name, select one of the matches from the list, and press the Enter key. ## Shutting down To shut down your computer, select "Log Out" from the "System" menu, then click "Shut Down". You can also choose "Restart" if you want to restart your computer, or "Log Out" if you would like to log out of the current graphical session. ## Searching in application menus Click into the "Search in Menu" box in the menu bar, or press Alt+Space. Then enter a few characters of the menu entry you would like to execute, select one of the matches from the list, and press the Enter key. ## Date and time Date and time in your current timezone are displayed at the right hand side of the menu bar. --- ## File: user/components/utilities/create-live-media.md # Create Live Media A __Live Medium__ is a storage device that can be used to start your computer with the helloSystem without having to install helloSystem to the internal storage of the computer. It allows you to try out helloSystem without making any changes to the software installed on your computer. Almost all functionality of helloSystem is available in Live mode, with very few exceptions. Changes being made, including files created, will be discarded when the system is shut down or retarted. The __Create Live Media__ utility provides an easy and convenient way to create bootable Live Media on devices such as USB sticks. It downloads and writes Live ISOs to devices in one go. This is useful if you are running helloSystem and would like to write a newer (or experimental) version of the system to a bootable storage device. ## Prerequisites In order to create a Live medium, you need * A computer running any version of helloSystem with the __Create Live Media__ utility * A fast internet connection (a typical download is around 2 GiB) * A suitable external storage device, e.g., a USB3 device. USB2 devices can be used but performance may be degraded. On some systems, other storage media such as SD cards or microSD cards can be used. Consult the documentation that came with your computer to determine which type of media can be used to start your computer. ``` .. note:: The **Create Live Media** utility cannot be used on other operating systems such as Windows, Linux, or macOS. If you would like to create Live Media for helloSystem using one of those operating systems, you can use applications that can write images to USB storage devices, such as [balenaEtcher](https://www.balena.io/etcher/). ``` ## Downloading and writing Live Media The __Create Live Media__ utility downloads and writes a Live ISO image in one go to a storage medium. Open the __Create Live Media__ utility and follow the instructions on screen. ``` .. warning:: The **Create Live Media** utility will overwrite the entire contents of the selected device, including all of its pre-existing partitions. Take extra caution when selecting the target device. This operation cannot be undone. ``` Once the image has been written to the device successfully, you can restart your computer to start from the Live Medium, or remove the device and insert it into another computer to start that computer from the Live Medium. --- ## File: user/components/utilities/install.md # Install FreeBSD Once you have tried out helloSystem from the live medium, you may want to install the system to the hard disk in your computer, or an externally attached storage device. The __Install FreeBSD__ utility lets you install helloSystem on your computer from a running Live system. ``` .. note:: The utility is called **Install FreeBSD** to signify that helloSystem contains a largely unmodified FreeBSD core operating system. It might be renamed "Install helloSystem" in the future. ``` When you install helloSystem using the __Install FreeBSD__ utility, the installed system will behave like the Live system in most aspects. ## Prerequisites * A bootable helloSystem Live Medium * A computer capable of starting from the Live Medium * An internal or external storage device with 8 GB of storage space. More space is highly recommended to allow for adding applications and documents ## Installing helloSystem Start your computer from a helloSystem Live Medium. Open the __Install FreeBSD__ utility and follow the instructions on screen. The installer starts by presenting a summary of FreeBSD. Click on "Continue". To install the software, you must agree to the terms of the software license agreemement. Click on "Continue" to proceed. Click on a destination disk on which the operating system should be installed. A warning will inform you that the entire disk will be erased. Confirm whether you want to do this by clicking on the appropriate button. ``` .. warning:: The **Install FreeBSD** utility will overwrite the entire contents of the selected device, including all of its pre-existing partitions. Take extra caution when selecting the target device. This operation cannot be undone. ``` If you are really sure that you have selected the correct device, click "Continue". In the next step, you will create an account for the main user of the computer. The information entered here is used to identify the main user of the computer. This user will have administrative permissions (will be member of the `wheel` group). * In the field __Full Name__, enter your first name(s), followed by a blank, followed by your last name. Example: `John Doe`. This field can be left blank if you prefer not to provide your full name * The field __Username__ will be automatically populated with a suggested username. It must not contain any special characters such as blanks. You can override the suggested default if you like. Example: `jdoe` * Enter a password into the __Password__ field. Repeat the same password in the __Retype Password__ field. These fields can be left blank if you prefer not to use a password, but this will mean that anyone with access to your computer will be able to log in, and you will not be able to log in over the network * The field __Computer Name__ will be automatically populated with a suggested computer name (hostname). This name will be used to identify your computer on the local area network. It must not contain any special characters such as blanks. You can override the suggested default if you like. Example: `Johns-TravelMate-B117-M` * Check the checkbox __Enable users to log in over the network (ssh)__ if you would like to allow accessing the computer remotely. By default, this requires a passwort to be set for the computer account * Check the checkbox __Set time zone based on current location__ if you would like timezone on the installed system to be set automatically. This feature requires an active internet connection Click "Continue" to proceed. The system will be installed to the selected disk. This process typically takes a couple of minutes depending on your system configuration, during which a progress bar will be shown. You can click on "Installer Log" at any time to see a detailed log of the actions performed by the installer and details on any possible errors. Once the installation has completed, remove the Live medium from your computer and click the "Restart" button to start the newly installed system. --- ## File: .github/workflows/main.yml # This is a basic workflow to help you get started with Actions name: CI # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: if: "!contains(github.event.head_commit.message, 'ci skip')" # The type of runner that the job will run on runs-on: ubuntu-latest env: G_TOKEN: ${{secrets.GITHUB_TOKEN}} # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Build docs run: sudo -E bash -ex buildDocs.sh # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project.