Skip to content

NAP 0.6.0
Compare
Choose a tag to compare
@cklosters cklosters released this 16 Jun 12:29
· 948 commits to main since this release
v0.6.0
aa2e6b1
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

Major release that introduces new features, general improvements and the usual set of fixes.

Download

Warning

This release is not compatible with older NAP projects - version 0.5 and below. A new 0.5 branch has been created for legacy purposes that will continue to receive critical updates and fixes (for the time being). A porting guide will be made available to help you port your existing project to NAP 0.6.

New Features

We have reworked the entire build system to provide a more streamlined project management and build experience. The NAP compiled framework release and source context are now more unified, making it possible to create, share and deploy the same module to both contexts without providing additional (arcane) build instructions. This lowers the amount of friction as it reduces the number of hoops a developer has to jump through trying to integrate a new set of features or third party dependency.

The project management documentation has been updated (rewritten) to reflect these changes.

User Modules

Users can now share their modules with others!

A list of publicly available user modules can be found at modules.nap.tech.

These modules are created, maintained and shared by NAP users, independent of NAP Framework.

Download & Install module

User modules can be installed from a zip or repository.

From zip

Download the module as .zip archive from (for example) Github and install it into the nap modules directory:

  1. Open a terminal
  2. Change into your NAP framework directory
  3. Install the module
./tools/install_module.sh ~/Downloads/napdatabase-main.zip

From repository

Clone the repository and set up the module in the nap modules directory:

  1. Open a terminal
  2. Change into your NAP modules directory
  3. Clone the repository
cd modules
clone https://github.com/naivisoftware/napdatabase.git
  1. Set it up
./../tools/setup_module.sh napdatabase

Share your module

You can share your module on modules.nap.tech by following this registration procedure.

A typical module has the following content, which will be included when the module is shared:

Content Directory Required
source code src yes
thirdparty dependencies thirdparty no
demo application demo no

Unified Contexts

The NAP (pre-compiled) package and source context now share - to large extent - the same layout, build instructions and tools. Subsequently: user modules and applications can now be deployed and used in both. Because of this change user modules (can) now include their own demo and third-party dependency, sitting directly in the root of the module directory. This simplifies the packaging, sharing and installation of a module substantially. It also helps developers track and understand dependencies better because everything is now more local to the code that uses it.

CMakeLists.txt files has been moved into framework-space. That framework-space logic is an evolution of what was previously used for Framework Release and is now located at cmake/nap_app.cmake and cmake/nap_module.cmake.

Custom logic belongs in module_extra.cmake and app_extra.cmake within the root of the module/app (not under dist like before). This logic is integrated after the target has been defined. In rare cases it might be desirable to execute extra logic before the target is defined. A new hook for that has been provided via optional files module_extra_pre_target.cmake and app_extra_pre_target.cmake.

Basic module structure

A super simple module with no third party library and no added CMake logic will look exactly as it would have before in Framework Release context:

src/...
module.json

Any extra CMake now also appears in the module root:

src/...
module.json
module_extra.cmake

If the module has a demo that will appear under demo:

demo/<DEMO_NAME>/...
src/...
module.json

With the <DEMO_NAME> appearing in the DemoApp element of module.json eg.:

{
    "Type": "nap::ModuleInfo", 
    "mID": "ModuleInfo", 
    "RequiredModules": [
        "napmath"
    ], 
    "WindowsDllSearchPaths": [],
    "DemoApp": "tween"
}

Third party libraries live under /thirdparty in their own directory and are paired with the CMake find module within /thirdparty/cmake_find_modules, eg:

demo/lineblending/...
src/...
thirdparty/etherdream/...
thirdparty/cmake_find_modules/Findetherdream.cmake
module.json
module_extra.cmake

Each module should also contain a .gitignore, used to prepare it for sharing etc (and one is provided when the module is created). System modules with third party libraries remain special in that they're provided compiled in Framework Release context. As a result there's more complexity in their build logic. See the module_extra.cmake for system modules.

Thirdparty deprecated

The thirdparty repository is no longer required because all (pre-compiled) dependencies are included (merged) in this repository. The priorities which determined where those libraries ended up located were:

  1. Reduce differences between the two build contexts
  2. Where possible locate the library within the system module using the lib

So in the majority of cases the libraries end up located at system_modules/<USING_MODULE_NAME>/thirdparty/<THIRDPARTY_LIB_NAME>, eg. system_modules/naprender/thirdparty/SDL2 The CMake find modules for those libraries are located within eg. system_modules/naprender/thirdparty/cmake_find_modules.

Libraries that aren't specific to a module are located under <NAP_ROOT>/thirdparty with their CMake find modules in <NAP_ROOT>/cmake/find_modules.

Module Deprecation

The following modules are no longer part of the core framework:

They have been moved to dedicated reposities and are listed on modules.nap.tech. They will be maintained by others, independent of the core release.

Custom CMake

We've focused on providing a streamlined build environment for people to start making applications and modules, together with trying out some demos. But sometimes that's not enough: you need to add your own build logic. For that purpose we've provided additional easy to integrate hooks that you can use to add custom CMake to your project and include third-party library dependencies.

Module naming consistency

Previously modules were prefixed with mod_, which was present in the module directory name under Framework Release context but not Source context. As discussed that now changes. All modules are prefixed with nap but mod_ is removed. Pascal case is no longer enforced in the module and app creator, the user can enter whatever they want, and whatever they enter is used everywhere (eg. class names, directory names, etc).

Build output dir consolidates to BUILD_TYPE-ARCH

Before this was different between contexts, and then in Source context it was also different between multi build type systems (macOS, Windows) and single build type (Linux). Now, as planned, it's just <BUILD_TYPE>-<ARCH> eg. Linux-x86_64.

/dist gone, /build_tools moved

/dist became a little irrelevant as the contexts consolidated. /build_tools roughly moved to /tools/buildsystem.

/tools/*.(sh|bat) in Source Context

Hinted at in the previous, but whether you're in Framework Release or Source context all of the tools/ scripts are accessible. Naturally some of these vary a little across context, eg. a ./tools/regenerate_app.sh someapp is just going to regenerate the whole solution in Source context.

App & Module directory shortcuts

Similarly whether from either context you can use the same module or app directory shortcuts.

For apps:

  • regenerate
  • build
  • package (Framework Release only)

For modules

  • regenerate
  • prepare_to_share (not for system modules)

.sh for all Unix scripts

In a concession against convention (Unix scripts shouldn't have extensions, it's bad practice) due to having Unix wrapper scripts visible in Source context on Windows .sh extensions were added to the Unix scripts. Then for consistency this was applied across contexts. As a result the minor changes were made to switch the scripts to POSIX sh from bash (in case somebody goes all odd and explicitly calls the interpreter to run the script). The other option, using .bash suffixes for all the files, would have been pretty ugly.

Moving away from *_DIST_FILES in CMake find modules

Where the philosophy for packaging a third party library was previously something like "let's cherry pick the parts we want, install them to a platform-specific clean directory structure and make a tidy CMake find module to match that" that now becomes "let's filter out other platform binaries but keep the same directory structure and CMake find module".

CMake function and macro consolidation

There was shared CMake logic all over the place without clear divisions, the majority of which is now in macros_and_functions.cmake. It's a work in progress but a step in the right direction. framework_release_packaging.cmake still exists.

Unix: RPATH inheritance

Previously there was a bunch of build logic around the place to handle providing RPATHs for modules that an executable or library depended on. That's now all largely handled through the LibrarySearchPaths element in module.json. The path mapping substitutions are used (but adding a MODULE_DIR in future would be useful). This is a lot cleaner.

New CMake variables

  • NAP_BUILD_CONTEXT is one of "source" or "framework_release"
  • NAP_THIRDPARTY_PLATFORM_DIR is used for mapping to the platform names we've used through thirdparty ("linux", "macos" or "msvc")
  • MODULE_EXTRA_LIBS_OPTIMIZED and MODULE_EXTRA_LIBS_DEBUG are now provided for linking to release and debug builds of libraries without having to resort to a CMake interface library. I believe this mainly impacts system modules in Framework Release at the moment.
  • Related to the above, MODULE_NAME_EXTRA_LIBS has been renamed to MODULE_EXTRA_LIBS (used for both build types)

Project to App naming

Project has been renamed to App. This ended up being reasonably broad and will likely impact a range of things.

/modules -> /system_modules, /user_modules -> /modules

/modules becomes /system_modules and /user_modules becomes /modules (as discussed). user_modules was awkward; for eg. there wasn't user_apps.

build.(sh|bat) in Source can build all

Before it was clunky to do a build all in Source on all platforms from CLI. Now that's possible (and runs by default if a target isn't specified).

build_dir/ becomes build/ on Linux

We no longer clash with scripts called 'build'

Napkin

Automatic project loading

Napkin now automatically loads the project in app release context, completely removing the need for end-users to configure their session in Napkin.

Automatic app runner configuration

Napkin attempts to find and set the application in the app runner after opening a project, removing the need to manually browse for the executable.

Automatic root detection

The NAP root is resolved before opening a project - making it easier to find projects in framework release and source context.

Documentation

Large parts of the manual at docs.nap.tech have been rewritten to accommodate these changes. The getting started tutorial has been redesigned to better align with the current state of NAP. It should guide new users better into understanding and working with NAP, including it's key components such as napkin, applications and the build system. The project management page has been rewritten to reflect all of the changes mentioned above. A great deal of time was invested into linking everything together, so users should be able to better explore the various parts of the ecosystem, including user modules, system documentation, the manual, source code, official releases etc.

Special thanks to @cheywood @TimGroeneboom @stijnvanbeek @lshoek @cklosters


Contributors

TimGroeneboom, cklosters, and 3 other contributors
Assets 6
Loading