shared-libs: add description

JIRA: RTOS-664

Author: Hubert Badocha

shared-libs/shared-libs.md

@@ -0,0 +1,31 @@
+# Shared libs
+
+Phoenix-RTOS supports building shared libs and dynamically-linked executables. Shared libs are support on all MMU platforms but aarch64 and on NOMMU arm. On NOMMU the FDPIC format is used.
+
+## Usage
+
+In target includes there are 3 variables connected to using shared libraries:
+- **LIBPHOENIX_PIC** - if libphoenix should be be built as PIC
+- **LIBPHOENIX_SHARED** - if shared libphoenix should be built
+- **HAVE_SHLIB** - defines if target supports shared libraries
+
+**LIBPHOENIX_\*** flags may be overriden in project to control if it is meant to use shared libraries on not.
+
+### Shared libs
+To compile a library as a shared include of `include $(static-lib.mk)` to `include $(shared-lib.mk)`.
+
+In cases of simple libraries this might be enough, however building a shared library is more similar to building a binary than a static library, thus more compilation options are available. Please refer for full list to `phoenix-rtos-build/makes/shared-lib.mk`. Most importantly libraries on which the shared library depends can be specified and few shared library specific options are available:
+- **SONAME** - library soname, defaults to $(NAME).so, to disable set to 'nothing'
+- **LOCAL_VERSION_SCRIPT** - version script relative to current makefile
+
+### Dynamically linked executable
+In most cases compilation of a dynamically-linked executable is as easy as changing `include $(binary.mk)` to `include $(binary-dyn.mk)`.
+
+`binary-dyn.mk` additionally allows to specify:
+- **DEP_LIBS_SHARED** - shared libraries from current repo needed to be compiled/installed before this component (shortcut for putting something in LIBS and DEPS)
+- **LIBS_SHARED** - names of the shared libs to link the binary against (without .so suffix)
+
+### ldconfig
+To create correct symlinks for shared libraries `ldconfig` needs to run at system boot. So, it has to be added to startup script on targets using shared libs. 
+
+Unfortunatelly, on SPARC targets read-only fs is used and user is on their own to correctly set paths in build time.