Migrating from borealis

此頁面尚未翻譯，以下為英文版。

Aurore is borealis under a new name. An app on xfangfang/borealis (the wiliwili branch) or on natinusala's moves to Aurore by changing its submodule and a few lines of CMake, and by renaming what it took from borealis (the brls namespace, <borealis.hpp>, the brls: XML tags, the BRLS_ macros): Aurore keeps none of borealis' names, and a search and replace does it (section 6, The names). This page lists those lines, then what looks or behaves differently afterwards.

1. The submodule

Replace borealis with Aurore, at the same path or a new one (library/aurore below, as in Aurore's own docs):

git submodule deinit -f library/borealis
git rm -f library/borealis
rm -rf .git/modules/library/borealis
git submodule add -b main https://github.com/JigSawFr/aurore.git library/aurore
git submodule update --init --recursive

Pin a release rather than following main: git -C library/aurore checkout vX.Y.Z, and read its entry in CHANGELOG.md before moving to the next one (before 1.0, a minor version may break the API). In code, AURORE_VERSION_AT_LEAST(0, 2, 0) tells which one is built.

2. The build

• C++20. Aurore and its headers need it: set(CMAKE_CXX_STANDARD 20) or CXX_STANDARD 20 on the app's target. RTTI and exceptions stay on (no -fno-rtti, no -fno-exceptions).
• The library's path. The app's variable for the library/ folder (BOREALIS_LIBRARY in borealis' template, any name will do) moves to the new path, and the two includes stay before project():

cmake set(AURORE_LIBRARY ${CMAKE_CURRENT_SOURCE_DIR}/library/aurore/library) include(${AURORE_LIBRARY}/cmake/commonOption.cmake) include(${AURORE_LIBRARY}/cmake/toolchain.cmake) project(my_app) add_subdirectory(${AURORE_LIBRARY} ${CMAKE_BINARY_DIR}/aurore)

• The target. The library target is Aurore::aurore; borealis is gone, without an alias. It brings its include directories, definitions and dependencies with it, so the app's own copies of them can go:

cmake target_link_libraries(my_app PRIVATE Aurore::aurore)

The test harness, if the app uses it, is Aurore::test (-DAURORE_BUILD_TESTS=ON, testing.md), its cases registered with aurore_add_tests(). - The options are prefixed: AURORE_PLATFORM, AURORE_WINDOW, AURORE_GRAPHICS, AURORE_LIBROMFS, AURORE_BUILD_TESTS, AURORE_DEV_TOOLS… (platforms.md). borealis' names are no longer read: PLATFORM_DESKTOP=ON is AURORE_PLATFORM=DESKTOP, USE_SDL2=ON is AURORE_WINDOW=SDL2, USE_DEKO3D=ON is AURORE_GRAPHICS=DEKO3D, USE_LIBROMFS is AURORE_LIBROMFS, BRLS_BUILD_TESTS, BRLS_DEV_TOOLS, BRLS_INSPECTOR, BRLS_UNITY_BUILD and BRLS_FONTSTASH_STREAM are AURORE_BUILD_TESTS…, and the variable BRLS_RESOURCES_DIR or CUSTOM_RESOURCES_DIR (the folder that holds resources/ on a desktop) is AURORE_RESOURCES_ROOT. PLATFORM_* and USE_* are still set as plain variables after commonOption.cmake, for the app's own tests. The presets in CMakePresets.json are Aurore's own, for the demo. - The Switch keeps devkitPro's compiler flags now (the Cortex-A57 tuning, the TLS model): an app that put them back by hand can stop. libpulsar is no longer linked: borealis' Switch sounds had been off for years, and still are.

3. The resources

Aurore's resources/ has more than borealis': the library's and Cadran's strings in 15 languages (i18n/<language>/: cadran.json, hints.json, a11y.json, themes.json), the emoji (img/emoji/), the fonts (Inter, PromptFont and Sora in font/, Material Icons in material/), the theme folders (themes/). The app's resources go on top of Aurore's, at each build: copy Aurore's folder, then the app's over it (the ASSEMBLE_RESOURCES step of template/CMakeLists.txt does it, and leaves the demo's own files out). A copy made once goes stale at the next update of the submodule.

4. The look: Cadran

Aurore draws every app in Cadran's look, the look of PlayGuard and PlayShelf, without a line of code: an icon rail for the sidebar, cards for the lists, its dialogs and pickers, its palettes. Two choices:

• Keep borealis' look: aurore::Application::setCadran(false) before init(). The screens look as before, with Aurore's fixes and features.
• Take Cadran's: fill in what it asks of the app (ui::hooks: the main screen and its tabs, the rail's icons, the version) and keep the user's choices (ui::Prefs), as cadran.md says. Each hook left empty does nothing, so it can be done screen by screen.

Licence. borealis is Apache 2.0; Cadran is GPLv3, and is linked into every app built with Aurore, whichever look it shows: an app built with Aurore is GPLv3 (NOTICE).

5. What changes on screen

Most apps build and run unchanged. What to look at after the move:

The README's Every change and its API lists the rest: new views, styles per state, the inspector, hot reload, the test harness.

6. The names

Every name borealis gave the library has an Aurore one, and only the Aurore one works: an app that still uses brls::, <borealis.hpp> or BRLS_ no longer builds, and a brls: XML tag, a brls/ theme key or a BRLS_ environment variable is no longer read.

Moving an app's code to the new names is a search and replace; git grep finds what is left:

git grep -l -E 'brls|borealis|BRLS_|BOREALIS_' -- src include resources CMakeLists.txt | xargs sed -i -E \
    -e 's/\bnamespace brls\b/namespace aurore/g' -e 's/\bbrls::/aurore::/g' -e 's/\bbrls_(add_tests|web_button)\b/aurore_\1/g' \
    -e 's/<borealis(\.hpp|\/)/<aurore\1/g' -e 's/\bBRLS_|\bBOREALIS_/AURORE_/g' -e 's/\bBrls([A-Z])/Aurore\1/g' \
    -e 's/\bbrls:([A-Z])/aurore:\1/g' -e 's/([@"\/ ])brls\//\1aurore\//g'

Look at the result before committing: an app's own name that starts with BRLS_ is changed too, and BRLS_RESOURCES_DIR becomes AURORE_RESOURCES_ROOT, not AURORE_RESOURCES_DIR (libromfs' environment variable).

7. Afterwards

• Turn on the debugging aids while checking the screens: AURORE_INSPECTOR=1 and AURORE_HOT_RELOAD=$PWD/resources (environment.md).
• architecture.md explains the loop, the focus, ownership and threads; the API reference has each class and function.
• Issues and fixes go to JigSawFr/aurore; a fix that belongs upstream is welcome there too.

在 GitHub 上編輯此頁