View Source Bundlex.Project behaviour (Bundlex v1.4.5)

Behaviour that should be implemented by each project using Bundlex in the bundlex.exs file.

Summary

Types

Type describing input project configuration.

Type describing configuration of a native.

t()

Struct representing bundlex project.

Callbacks

Callback returning project configuration.

Functions

Returns the project struct of given application.

Determines if module is a bundlex project module.

Types

@type config() :: [{:natives | :libs, [{native_name(), native_config()}]}]

Type describing input project configuration.

It's a keyword list, where natives and libs can be specified. Libs are native packages that are compiled as static libraries and linked to natives that have them specified in deps field of their configuration.

@type native_config() :: [
  sources: [String.t()],
  includes: [String.t()],
  lib_dirs: [String.t()],
  libs: [String.t()],
  os_deps: [os_dep()],
  pkg_configs: [String.t()],
  deps: [{Application.app(), native_name() | [native_name()]}],
  src_base: String.t(),
  compiler_flags: [String.t()],
  linker_flags: [String.t()],
  language: :c | :cpp,
  interface: native_interface() | [native_interface()],
  preprocessor:
    [Bundlex.Project.Preprocessor.t()] | Bundlex.Project.Preprocessor.t()
]

Type describing configuration of a native.

Configuration of each native may contain following options:

  • sources - C files to be compiled (at least one must be provided).

  • preprocessors - Modules that will pre-process the native. They may change this configuration, for example by adding new keys. An example of preprocessor is Unifex. See Bundlex.Project.Preprocessor for more details.

  • interface - Interface used to integrate with Elixir code. The following interfaces are available:

    • :nif - dynamically linked to the Erlang VM (see Erlang docs)
    • :cnode - executed as separate OS processes, accessed through sockets (see Erlang docs)
    • :port - executed as separate OS processes (see Elixir Port docs) Specifying no interface is valid only for libs.
  • deps - Dependencies in the form of {app, lib_name}, where app is the application name of the dependency, and lib_name is the name of lib specified in Bundlex project of this dependency. Empty list by default. See Dependencies section below for details.

  • os_deps - List of external OS dependencies. It's a keyword list, where each key is the dependency name and the value is a provider or a list of them. In the latter case, subsequent providers from the list will be tried until one of them succeeds. A provider may be one of:

    • pkg_config - Resolves the dependency via pkg-config. Can be either {:pkg_config, pkg_configs} or just :pkg_config, in which case the dependency name will be used as the pkg_config name.

    • precompiled - Downloads the dependency from a given url and sets appropriate compilation and linking flags. Can be either {:precompiled, url, libs} or {:precompiled, url}, in which case the dependency name will be used as the lib name. Precompiled dependencies can be disabled via configuration globally:

      config :bundlex, :disable_precompiled_os_deps, true

      or for given applications (Mix projects), for example:

      config :bundlex, :disable_precompiled_os_deps,
        apps: [:my_application, :another_application]

      Note that this will affect the natives and libs defined in the bundlex.exs files of specified applications only, not in their dependencies.

    Check os_dep/0 for details.

  • pkg_configs - (deprecated, use os_deps instead) Names of libraries for which the appropriate flags will be obtained using pkg-config (empty list by default).

  • language - Language of native. :c or :cpp may be chosen (:c by default).

  • src_base - Native files should reside in project_root/c_src/<src_base> (application name by default).

  • includes - Paths to look for header files (empty list by default).

  • lib_dirs - Absolute paths to look for libraries (empty list by default).

  • libs - Names of libraries to link (empty list by default).

  • compiler_flags - Custom flags for compiler. Default -std flag for :c is -std=c11 and for :cpp is -std=c++17.

  • linker_flags - Custom flags for linker.

@type native_interface() :: :nif | :cnode | :port
@type native_language() :: :c | :cpp
@type native_name() :: atom()
@type os_dep() :: {name :: atom(), os_dep_provider() | [os_dep_provider()]}
@type os_dep_provider() ::
  :pkg_config
  | {:pkg_config, pkg_configs :: String.t() | [String.t()]}
  | {:precompiled, url :: String.t()}
  | {:precompiled, url :: String.t(), libs :: String.t() | [String.t()]}
@type t() :: %Bundlex.Project{
  app: atom(),
  config: config(),
  module: module(),
  src_path: String.t()
}

Struct representing bundlex project.

Contains the following fields:

  • :config - project configuration
  • :src_path - path to the native sources
  • :module - bundlex project module
  • :app - application that exports project

Callbacks

@callback project() :: config()

Callback returning project configuration.

Functions

Link to this function

get(application \\ MixHelper.get_app!())

View Source
@spec get(application :: atom()) ::
  {:ok, t()}
  | {:error,
     :invalid_project_specification
     | {:no_bundlex_project_in_file, path :: binary()}
     | :unknown_application}

Returns the project struct of given application.

If the module has not been loaded yet, it is loaded from project_dir/bundlex.exs file.

@spec native_config_keys() :: [atom()]
@spec project_module?(module()) :: boolean()

Determines if module is a bundlex project module.