Migrating from borealis

Cette page n'est pas encore traduite : la voici en anglais.

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; its code keeps compiling with borealis' names (the brls namespace, <borealis.hpp>, the brls: XML tags, the BRLS_ macros), deprecated aliases of Aurore's own until 1.0, and moves to the new ones at its own pace (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 (PLATFORM_*, USE_GLFW, USE_SDL2, USE_DEKO3D, USE_LIBROMFS…, and BRLS_BUILD_TESTS, BRLS_DEV_TOOLS, BRLS_INSPECTOR, BRLS_UNITY_BUILD, BRLS_FONTSTASH_STREAM) still work, with a deprecation warning, and the platform ones stay set as plain variables for the app's own tests. The variable BRLS_RESOURCES_DIR (the folder that holds resources/ on a desktop) is now AURORE_RESOURCES_ROOT; the old name is still read. 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. The old names are deprecated aliases until Aurore 1.0: an app builds unchanged, and moves to the new names when it likes.

Defining AURORE_NO_DEPRECATION_WARNINGS (target_compile_definitions(my_app PRIVATE AURORE_NO_DEPRECATION_WARNINGS)) silences the messages and warnings while the app has not moved yet; the old names keep working.

One thing does not carry over: a namespace alias cannot be opened again, so a forward declaration in the old namespace no longer compiles:

namespace brls { class Activity; }   // error: brls is an alias of aurore
namespace aurore { class Activity; } // the new name (or include the header)

The same goes for code that defines the library's own functions in namespace brls { … } (a test that stands in for part of it): it opens namespace aurore instead.

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 | xargs sed -i -E \
    -e 's/\bnamespace brls\b/namespace aurore/g' -e 's/\bbrls::/aurore::/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 is built with doxygen docs/Doxyfile.
• Issues and fixes go to JigSawFr/aurore; a fix that belongs upstream is welcome there too.

Modifier cette page sur GitHub