Source Code Structure
SAFplus source code is located under the "src" directory, examples are located under "examples". Every SAFplus library and component is located under the "src" directory. Special directories are as follows:
- The "src/include" directory contains ALL header files that an application will need when using SAFplus services. This is the ONLY directory that applications will need to include as a -I flag. You may create symbolic links from this directory to header files in component-specific subdirectories if you would like to keep your component header files in component directories.
- Third party open source software that is not generally provided by a Linux distribution is located in the "src/3rdparty" subdirectory.
- The "common" directory contains autogenerated YANG objects. Do not add anything here
- The "mk" directory contains all files need by the build system, except of course for the "Makefile" located to build in each directory. For more information see Makefile System.
- osal: Operating System Adaptation Layer. Use Boost for most of your OS functions. If boost does not have the needed feature, put it in here.
- utils: Put functions of general applicability in here.
Component source code structure
Inside a component directory code is structured as follows:
[component]
[files to build the client library (if any)]
server
[files to build the server side of the component (if it has a server)]
test
[unit tests for this component]
Makefile System
Makefiles are structured so that a user can build in any subdirectory simply by typing "make". At the top, every Makefile includes the file "src/mk/preface.mk" which defines make variables that should be used in the rest of the makefile. At the bottom, every makefile includes "src/mk/safplus_targets.mk" which defines how other SAFplus targets (libraries, programs, tests) can be made.
Makefile Variables
These make variables are only set to values if they are not already set. They can be overridden via environment variables, make command line parameters, or via parent makefiles.
Source code Locations
These variables define where source code is located:
SAFPLUS_MAKE_DIR: the directory containing make related files, e.g. ".../src/mk"
SAFPLUS_SRC_DIR: the SAFplus source root directory, e.g. ".../src"
SAFPLUS_INC_DIR: the SAFplus include directory, e.g. ".../src/include". This is the only directory the applications need to include to get access to all SAFplus services headers.
SAFPLUS_3RDPARTY_DIR: the SAFplus 3rd party directory, e.g. ".../src/3rdparty"
Useful Inside Makefiles
TARGET_OS: what operating system are you building for? By default this is the output of "uname -r". You can override this variable to ensure that a crossbuild's output is put in a unique location.
TARGET_PLATFORM: what architecture are you building for? By default this is the output of "uname -p". You can override this variable to ensure that a crossbuild's output is put in a unique location.
LINK_SO_LIBS: The standard libraries that SAFplus needs in order to link
LINK_SO: How to create a shared library. Usage: $(LINK_SO) [output file] [input .o files and .so files]
LINK_EXE: How to create an executable program. Usage: $(LINK_EXE) [output file] [input .o and .so files]
Output Locations
By default all output files are stored in the directory ".../src/target/$(TARGET_OS)/$(TARGET_PLATFORM). This allows cross compiles to be output into a new directory so they do not interfere with eachother or the native compilation. The directory structure is as follows:
.../src/target/$(TARGET_OS)/$(TARGET_PLATFORM)
lib : SAFplus libraries
bin : SAFplus executables
obj : .o files not part of libmw.so
mwobj : .o files that are part of libmw.so
test : unit tests
install : install "prefix" for all 3rdparty code. Everything in here becomes part of the final package (unless the packager deliberately omits dev directories like "include").
bin
include
lib
share
[...and more...]These variables define output target directories described above.
INSTALL_DIR: All 3rdparty make;make install output goes here, in the linux standard subdirectory structure (include,lib). This entire directory will become part of the final package so users can copy additional files into this subdirectory to include them.
LIB_DIR: SAFplus library output directory. Individual component libraries, plugins, and the full libmw.so will be generated into this directory. The packaging software can either choose to include just libmw.so, or include individual component libraries.
BIN_DIR: SAFplus executable files.
TEST_DIR: SAFplus unit tests.
OBJ_DIR: All object files that are NOT PART of libmw.so should go in this directory or in subdirectories.
MWOBJ_DIR: All object files that are PART of libmw.so should go here.
Makefile Detailed Structure
The following is an example Makefile:
SAFPLUS_LOG_LIB:=1
include ../mk/preface.mk
CLIENT_H := $(wildcard *.hxx) $(wildcard $(SAFPLUS_INC_DIR)/*.hpp) $(wildcard $(SAFPLUS_INC_DIR)/*.hxx)
CLIENT_SRC := $(wildcard *.cxx)
CLIENT_OBJ := $(subst .cxx,.o,$(CLIENT_SRC))
CLIENT_OBJ := $(addprefix $(MWOBJ_DIR)/,$(subst .cxx,.o,$(CLIENT_SRC)))
# Specify the required libraries
SAFPLUS_LIBS := clOsal clUtils
# Then use these in the make rule
SAFPLUS_DEP_LIBS := $(addsuffix .so,$(addprefix $(LIB_DIR)/lib,$(SAFPLUS_LIBS)))
SAFPLUS_LINK_LIBS := -L$(LIB_DIR) $(addprefix -l,$(SAFPLUS_LIBS))
Release all: $(LIB_DIR)/libclLog.so
$(SAFPLUS_TARGET)/lib/libclLog.so: $(CLIENT_OBJ) $(SAFPLUS_DEP_LIBS)
$(LINK_SO) $@ $(CLIENT_OBJ) $(SAFPLUS_LINK_LIBS) $(LINK_SO_LIBS)
$(MWOBJ_DIR)/%.o: %.cxx Makefile $(SERVER_H)
$(COMPILE_CPP) $@ $<
clean:
rm -f $(SAFPLUS_TARGET)/lib/clLog.o $(CLIENT_OBJ)
include $(SAFPLUS_MAKE_DIR)/safplus_targets.mk