From b9b3328764647cd1cfc164023c0e0183ff018b74 Mon Sep 17 00:00:00 2001 From: benefactarch Date: Tue, 29 Aug 2023 22:57:34 -0400 Subject: [PATCH] chore: readme --- README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1024c2d..acaae84 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,9 @@ includes = [] include_numpy = false include_somelib = { pkg = "pyarrow", include="get_include", libraries="get_libraries", library_dirs="get_library_dirs", required_call="create_library_symlinks" } +define_macros = [ + ["NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION"], +] ``` ## Configuration Options @@ -82,9 +85,9 @@ include_somelib = { pkg = "pyarrow", include="get_include", libraries="get_libra | Field | Type | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | src | `str \| None` 
 directory within `src` dir or `.`  which aliases the package being built. e.g. `package_a` -> `src/package_a_lib` 
 `src = "package_a"` | -| directives | directives to cython (see cython docs) | -| compile_args | str or `{ platforms = ["*"] \| "*", arg = str }` | -| extra_link_args | str or `{ platforms = ["*"] \| "*", arg = str }` | +| directives | directives to cython (see [compiler directives]) | +| compile_args | str or `{ platforms = ["*"] \| "*", arg = str }`. see [extensions] for what args may be relevant | +| extra_link_args | str or `{ platforms = ["*"] \| "*", arg = str }`. see [extensions] for what args may be relevant | | env | `{ env = "VAR1", arg = "VALUE", platforms = ["*"], arch = ["*"] }`
 if flag is one of:
 - ARFLAGS
 - LDSHARED 
 - LDFLAGS
 - CPPFLAGS 
 - CFLAGS 
 - CCSHARED
the current env vars will be merged with the value (provided platform & arch applies), separated by a space. This can be enabled by adding `{ env = "MYVAR" ... , merges = true }` to the definition. | | includes | list str | | includes\_{package} | `{ pkg = str, include = str, libraries = str\| None, library_dirs = str \| None , required_call = str \| None }` 
where all fields, but `pkg`, are attributes of `pkg` in the type of `callable() -> list[str] \| str` \| `list[str] \| str`. `pkg` is a module, or loadable module object, which may be imported through `import x.y.z`. | @@ -93,7 +96,8 @@ include_somelib = { pkg = "pyarrow", include="get_include", libraries="get_libra | parallel | bool = False 
if parallel, add openmp headers
important: if using macos, you need the *homebrew* llvm vs _apple's_ llvm in order to pass `-fopenmp` to clang compiler | | compiler | compiler used at build-time. if `msvc` (Microsoft Visual Studio), `/openmp` is used as argument to compile instead of `-fopenmp`  when `parallel = true`. `default = false` | | compile_py | whether to include `.py` files when building cython exts. note, this can be enabled & you can do per file / matched file ignores as below. `default = true` | -| \*\* kwargs | keyword = value pair arguments to pass to the extension module when building | +| define_macros | list of list str (of len 1 or 2). len 1 == [KEY] == `#define KEY FOO` . len 2 == [KEY, VALUE] == `#define KEY VALUE`. see [extensions] | +| \*\* kwargs | keyword = value pair arguments to pass to the extension module when building. see [extensions] | ### Files @@ -113,3 +117,7 @@ aliases = {"abclib._filewithoutsuffix" = "abclib.importalias"} ## License `hatch-cython` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license. + +[extensions]: (https://docs.python.org/3/distutils/apiref.html#distutils.core.Extension) + +[compiler directives]:(https://cython.readthedocs.io/en/latest/src/userguide/source_files_and_compilation.html#compiler-directives))