{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "building:compilers_and_options", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [], "title": [ { "__type": "Text", "__tag": 4046, "value": "Compiler selection and customizing a build" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson supports the standard environment variables " }, { "__type": "InlineCode", "__tag": 4051, "value": "CC" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "CXX" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "FC" }, { "__type": "Text", "__tag": 4046, "value": " to select specific C, C++ and/or Fortran compilers. These environment variables are documented in " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "the reference tables in the Meson docs" } ], "url": "https://mesonbuild.com/Reference-tables.html#compiler-and-linker-flag-environment-variables", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that environment variables only get applied from a clean build, because they affect the configure stage (i.e., " }, { "__type": "InlineCode", "__tag": 4051, "value": "meson setup" }, { "__type": "Text", "__tag": 4046, "value": "). An incremental rebuild does not react to changes in environment variables - you have to run " }, { "__type": "InlineCode", "__tag": 4051, "value": "git clean -xdf" }, { "__type": "Text", "__tag": 4046, "value": " and do a full rebuild, or run " }, { "__type": "InlineCode", "__tag": 4051, "value": "meson setup --reconfigure" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Selecting a specific compiler" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson by design prefers builds being configured through command-line options passed to " }, { "__type": "InlineCode", "__tag": 4051, "value": "meson setup" }, { "__type": "Text", "__tag": 4046, "value": ". It provides many built-in options:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For enabling a debug build and the optimization level, see the next section on \"build types\"," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Enabling " }, { "__type": "InlineCode", "__tag": 4051, "value": "-Werror" }, { "__type": "Text", "__tag": 4046, "value": " in a portable manner is done via " }, { "__type": "InlineCode", "__tag": 4051, "value": "-Dwerror=true" }, { "__type": "Text", "__tag": 4046, "value": "," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Enabling warning levels is done via " }, { "__type": "InlineCode", "__tag": 4051, "value": "-Dwarning_level=" }, { "__type": "Text", "__tag": 4046, "value": ", with " }, { "__type": "InlineCode", "__tag": 4051, "value": "" }, { "__type": "Text", "__tag": 4046, "value": " one of " }, { "__type": "InlineCode", "__tag": 4051, "value": "{0, 1, 2, 3, everything}" }, { "__type": "Text", "__tag": 4046, "value": "," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There are many other builtin options, from activating Visual Studio (" }, { "__type": "InlineCode", "__tag": 4051, "value": "-Dvsenv=true" }, { "__type": "Text", "__tag": 4046, "value": ") and building with link time optimization (" }, { "__type": "InlineCode", "__tag": 4051, "value": "-Db_lto" }, { "__type": "Text", "__tag": 4046, "value": ") to changing the default C++ language level (" }, { "__type": "InlineCode", "__tag": 4051, "value": "-Dcpp_std='c++17'" }, { "__type": "Text", "__tag": 4046, "value": ") or linker flags (" }, { "__type": "InlineCode", "__tag": 4051, "value": "-Dcpp_link_args='-Wl,-z,defs'" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a comprehensive overview of options, see " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson's builtin options docs page" } ], "url": "https://mesonbuild.com/Builtin-options.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson also supports the standard environment variables " }, { "__type": "InlineCode", "__tag": 4051, "value": "CFLAGS" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "CXXFLAGS" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "FFLAGS" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "LDFLAGS" }, { "__type": "Text", "__tag": 4046, "value": " to inject extra flags - with the same caveat as in the previous section about those environment variables being picked up only for a clean build and not an incremental build." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Adding a custom compiler or linker flag" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson provides different build types while configuring the project. You can see the available options for build types in " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "the \"core options\" section of the Meson documentation" } ], "url": "https://mesonbuild.com/Builtin-options.html#core-options", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Assuming that you are building from scratch (do " }, { "__type": "InlineCode", "__tag": 4051, "value": "git clean -xdf" }, { "__type": "Text", "__tag": 4046, "value": " if needed), you can configure the build as following to use the " }, { "__type": "InlineCode", "__tag": 4051, "value": "debug" }, { "__type": "Text", "__tag": 4046, "value": " build type " } ] }, { "__type": "Code", "__tag": 4050, "value": "meson setup build --buildtype debug --prefix=$PWD/build-install", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now, you can use the " }, { "__type": "InlineCode", "__tag": 4051, "value": "spin" }, { "__type": "Text", "__tag": 4046, "value": " interface for further building, installing and testing SciPy " } ] }, { "__type": "Code", "__tag": 4050, "value": "spin -s linalg", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This will work because after initial configuration, Meson will remember the config options." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Using different build types with Meson" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By default, " }, { "__type": "InlineCode", "__tag": 4051, "value": "ninja" }, { "__type": "Text", "__tag": 4046, "value": " will launch " }, { "__type": "InlineCode", "__tag": 4051, "value": "2*n_cpu + 2" }, { "__type": "Text", "__tag": 4046, "value": ", with " }, { "__type": "InlineCode", "__tag": 4051, "value": "n_cpu" }, { "__type": "Text", "__tag": 4046, "value": " the number of physical CPU cores, parallel build jobs. This is fine in the vast majority of cases, and results in close to optimal build times. In some cases, on machines with a small amount of RAM relative to the number of CPU cores, this leads to a job running out of memory. In case that happens, lower the number of jobs " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " such that you have at least 2 GB RAM per job. For example, to launch 6 jobs " } ] }, { "__type": "Code", "__tag": 4050, "value": "python -m pip install . -Ccompile-args=\"-j6\"", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "or " } ] }, { "__type": "Code", "__tag": 4050, "value": "spin build -j6", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Controlling build parallelism" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It may be useful to have several builds of SciPy in the same repo, for example to compare the differences between two compilers for diagnosing an issue. As discussed, Meson is fully out-of-place, so different builds will not interfere with each other. We assume in the rest of this section that GCC is the default. For example, let us build using GCC and Clang." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Build with GCC " } ] }, { "__type": "Code", "__tag": 4050, "value": "spin build", "execution_status": null } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Using the above command, meson will build with the (default) GCC compilers in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "build" }, { "__type": "Text", "__tag": 4046, "value": " directory, and install to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "build-install" }, { "__type": "Text", "__tag": 4046, "value": " directory." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Build with Clang " } ] }, { "__type": "Code", "__tag": 4050, "value": "CC=clang CXX=clang++ FC=gfortran spin --build-dir=build-clang build", "execution_status": null } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Using the above commands, Meson will build with the Clang, Clang++ and Gfortran compilers in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "build-clang" }, { "__type": "Text", "__tag": 4046, "value": " directory, and then install SciPy into " }, { "__type": "InlineCode", "__tag": 4051, "value": "build-clang-install" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson will remember the compiler selection for the " }, { "__type": "InlineCode", "__tag": 4051, "value": "build-clang" }, { "__type": "Text", "__tag": 4046, "value": " directory and it cannot be changed, so each future invocation of " }, { "__type": "InlineCode", "__tag": 4051, "value": "spin --build-dir=build-clang " }, { "__type": "Text", "__tag": 4046, "value": " it will automatically use Clang." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tip: use an alias to make this easier to use, e.g., " }, { "__type": "InlineCode", "__tag": 4051, "value": "alias dev-clang=\"spin --build-dir=build-clang\"" }, { "__type": "Text", "__tag": 4046, "value": " and then " }, { "__type": "InlineCode", "__tag": 4051, "value": "dev-clang build" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A common reason to have two builds is to compare between them. For example, to run the " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy.linalg" }, { "__type": "Text", "__tag": 4046, "value": " tests for builds with both compilers, do " } ] }, { "__type": "Code", "__tag": 4050, "value": "spin -s linalg # run tests for the GCC build\nspin --build-dir build-clang -s linalg # run tests for the Clang build", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Use GCC and Clang builds in parallel" } ], "level": 1, "target": null } ], "local_refs": [] }