======================== Using the RoSA Framework ======================== .. contents:: :local: General Recommendations ======================= Before starting to use the RoSA Framework, consult with the provided documentation. Especially, consider the followings: * :ref:`Documentation of the RoSA public API ` * :ref:`The used coding standards ` * :doc:`Issues` Building your own Project ========================= There are two main approaches to implement software based on features of the RoSA Framework, which are described as follows. Extending the RoSA Framework ---------------------------- Should some features be generally relevant in the context of the RoSA Framework, it may be reasonable to implement them as part of RoSA itself. Features may be implemented either as extensions for existing libraries and tools, or as new libraries, tools, and apps -- consider which way fits best. Refer to :doc:`Dev`. Creating a Standalone Project ----------------------------- One can easily create standalone projects based on the RoSA Framework. Such projects can be maintained separately from RoSA, but also can be integrated into the framework whenever that seems suitable. In the latter case, refer to the previous section, `Extending the RoSA Framework`_. For building a standalone project, one needs to define * the *include directories* with declaration of the RoSA public API for compiling the project, and * the *static libraries* with the implementation of RoSA features for linking the project as in * adding the directory containing the libraries to the library search path, and * defining the libraries the project is dependent on. Regarding library dependencies: it is safe to list all the RoSA libraries, but it is enough to list the real dependencies only. Do not forget that there are some :ref:`dependencies among libraries `, which requires listing all the libraries on a chain of dependency for successful linking. Depending on a Binary Release ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The easy way is to base the project on a binary release of RoSA. Howevever, note that binary releases are generated with :ref:`particular settings `, which may not always be suitable to use. When relying on a binary release of RoSA -- according to the :ref:`content of release packages ` --: * use `include` as additional include directory, and * use `lib` as additional directory for the library search path. Depending on a Custom Build ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Whenever it is not suitable to rely on a binary release, RoSA needs to be built manually first. Refer to :doc:`Build`. Note that only building libraries is required for building a standalone project depending on a custom build of RoSA. When relying on a custom build of RoSA -- according to the :ref:`location of the RoSA public API ` and :ref:`software results of a build ` --: * use `include` from both the source and the build directories as additional include directories, and * use `lib` from the build directory (or its proper subdirectory in case of a multi-configuration generator) as additional directory for the library search path. Visual Studio 2017 -- an Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Having a *Visual C++* project created in Visual Studio 2017, the followings need to be done in order to make the project dependent on RoSA: * add the RoSA-specific include directories to `Project/Properties/Configuration Properties/VC++ Directories/Include Directories`, * add the configuration-dependent directory containing the RoSA static libraries to `Project/Properties/Configuration Properties/VC++ Directories/Library Directories`, * add the RoSA library files to `Project/Properties/Configuration Properties/Linker/Input/Additional Dependencies`, * consult with :ref:`the build description for Visual Studio ` and set `Project/Properties/Configuration Properties/General/Platform Toolset` to a suitable value, `LLVM-vs`. Make sure in `Project/Properties` that `Configuration` and `Platform` of the project matches those of the RoSA build whose libraries are to be used for building the project.