Standalone

This example is designed to be used as a template for creating FleCSI-based application codes, and is intended as the last example in the tutorial. As such, this example provides the following components:

  • A basic CMake build system.

  • A simple control model.

  • A standard FleCSI-based main function.

We discuss each of these individually. However, in general, to use this example as a template for a real application, you should just change all occurrances of standalone to whatever namespace name you would like to use for your project.

Build System

The build system uses standard CMake, and is entirely defined in CMakeLists.txt:

#------------------------------------------------------------------------------#
#  @@@@@@@@  @@           @@@@@@   @@@@@@@@ @@
# /@@/////  /@@          @@////@@ @@////// /@@
# /@@       /@@  @@@@@  @@    // /@@       /@@
# /@@@@@@@  /@@ @@///@@/@@       /@@@@@@@@@/@@
# /@@////   /@@/@@@@@@@/@@       ////////@@/@@
# /@@       /@@/@@//// //@@    @@       /@@/@@
# /@@       @@@//@@@@@@ //@@@@@@  @@@@@@@@ /@@
# //       ///  //////   //////  ////////  //
#
# Copyright (c) 2016, Triad National Security, LLC
# All rights reserved
#------------------------------------------------------------------------------#

cmake_minimum_required(VERSION 3.12)

#------------------------------------------------------------------------------#
# Set the project name.
#------------------------------------------------------------------------------#

project(standalone LANGUAGES CXX C)

#------------------------------------------------------------------------------#
# FleCSI currently depends on C++17.
#------------------------------------------------------------------------------#

set(CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_STANDARD 17)

#------------------------------------------------------------------------------#
# Find the FleCSI installation.
#
# The easiest way to help CMake find FleCSI is to install it,
# and add the location to the CMAKE_PREFIX_PATH environment variable.
#------------------------------------------------------------------------------#

find_package(FleCSI REQUIRED)
include_directories(${FleCSI_INCLUDE_DIRS})

#------------------------------------------------------------------------------#
# Add an executable.
#------------------------------------------------------------------------------#

add_executable(standalone
  standalone.cc
  specialization/control.hh
)

#------------------------------------------------------------------------------#
# Add the FleCSI libraries and dependencies.
#------------------------------------------------------------------------------#

target_link_libraries(standalone
  ${FleCSI_LIBRARIES}
  ${FleCSI_LIBRARY_DEPENDENCIES}
)

To prepare this file for your project, you should do the following:

  • Change standalone to the name of your project wherever it occurs.

  • Update and add source files to the project.

  • Add any dependencies.

For the most part, if you wish to extend this tutorial in any way, you will need a working knowledge of CMake. Documentation for CMake is here.

Control Model

The control model for this exmample is located in specialization/control.hh. This implementation is consistent with the examples in Control Model Tutorial.

../../_images/standalone.png

Fig. 8 Control Model for Stand-Alone Application.

Main Function

The main function for this example is located in standalone.cc. Unless you need to initialize additional runtimes that are not handled internally by FleCSI, you can likely use this file as-is (except for renaming occurances of standalone to something sensible).

/*
    @@@@@@@@  @@           @@@@@@   @@@@@@@@ @@
   /@@/////  /@@          @@////@@ @@////// /@@
   /@@       /@@  @@@@@  @@    // /@@       /@@
   /@@@@@@@  /@@ @@///@@/@@       /@@@@@@@@@/@@
   /@@////   /@@/@@@@@@@/@@       ////////@@/@@
   /@@       /@@/@@//// //@@    @@       /@@/@@
   /@@       @@@//@@@@@@ //@@@@@@  @@@@@@@@ /@@
   //       ///  //////   //////  ////////  //

   Copyright (c) 2016, Triad National Security, LLC
   All rights reserved.
                                                                              */

#include "actions.hh"
#include "specialization/control.hh"

#include "flecsi/execution.hh"
#include "flecsi/flog.hh"

using namespace standalone;

int
main(int argc, char ** argv) {
  auto status = flecsi::initialize(argc, argv);

  if(status != flecsi::run::status::success) {
    return status == flecsi::run::status::help ? 0 : status;
  }

  status = control::check_options();

  if(status != flecsi::run::status::success) {
    flecsi::finalize();
    return status == flecsi::run::status::control ? 0 : status;
  } // if

  flecsi::log::add_output_stream("clog", std::clog, true);

  status = flecsi::start(control::execute);

  flecsi::finalize();

  return status;
} // main

Building the Stand-Alone Example

Build & Install FleCSI somewhere on your system, and make sure that the location is set in your CMAKE_PREFIX_PATH environement variable. Then, you can build this example like:

$ mkdir build
$ cd build
$ cmake ..
$ make