{ "__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:understanding_meson", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Building SciPy relies on the following tools, which can be considered part of the build system:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "meson" }, { "__type": "Text", "__tag": 4046, "value": ": the Meson build system, installable as a pure Python package from PyPI or conda-forge" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "ninja" }, { "__type": "Text", "__tag": 4046, "value": ": the build tool invoked by Meson to do the actual building (e.g. invoking compilers). Installable also from PyPI (on all common platforms) or conda-forge." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "pkg-config" }, { "__type": "Text", "__tag": 4046, "value": ": the tool used for discovering dependencies (in particular BLAS/LAPACK). Available on conda-forge (and Homebrew, Chocolatey, and Linux package managers), but not packaged on PyPI." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "meson-python" }, { "__type": "Text", "__tag": 4046, "value": ": the Python build backend (i.e., the thing that gets invoked via a hook in " }, { "__type": "InlineCode", "__tag": 4051, "value": "pyproject.toml" }, { "__type": "Text", "__tag": 4046, "value": " by a build frontend like " }, { "__type": "InlineCode", "__tag": 4051, "value": "pip" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "pypa/build" }, { "__type": "Text", "__tag": 4046, "value": "). This is a thin layer on top of Meson, with as main roles (a) interface with build frontends, and (b) produce sdists and wheels with valid file names and metadata." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Building with Meson happens in stages:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A configure stage (" }, { "__type": "InlineCode", "__tag": 4051, "value": "meson setup" }, { "__type": "Text", "__tag": 4046, "value": ") to detect compilers, dependencies and build options, and create the build directory and " }, { "__type": "InlineCode", "__tag": 4051, "value": "build.ninja" }, { "__type": "Text", "__tag": 4046, "value": " file," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A compile stage (" }, { "__type": "InlineCode", "__tag": 4051, "value": "meson compile" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "ninja" }, { "__type": "Text", "__tag": 4046, "value": "), where the extension modules that are part of a built SciPy package get compiled," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An install stage (" }, { "__type": "InlineCode", "__tag": 4051, "value": "meson install" }, { "__type": "Text", "__tag": 4046, "value": ") to install the installable files from the source and build directories to the target install directory," } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson has a good build dependency tracking system, so invoking a build for a second time will rebuild only targets for which any sources or dependencies have changed." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Understanding Meson" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Meson has " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "very good documentation" } ], "url": "https://mesonbuild.com/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "; it pays off to read it, and is often the best source of answers for \"how to do X\". Furthermore, an extensive pdf book on Meson can be obtained for free at https://nibblestew.blogspot.com/2021/12/this-year-receive-gift-of-free-meson.html" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To learn more about the design principles Meson uses, the recent talks linked from " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "mesonbuild.com/Videos" } ], "url": "https://mesonbuild.com/Videos.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " are also a good resource." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "To learn more about Meson" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is for teaching purposes only; there should be no need to execute these\nstages separately." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Assume we're starting from a clean repo and a fully set up conda environment " } ] }, { "__type": "Code", "__tag": 4050, "value": "git clone git@github.com:scipy/scipy.git\ngit submodule update --init\nmamba env create -f environment.yml\nmamba activate scipy-dev", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To now run the configure stage of the build and instruct Meson to put the build artifacts in " }, { "__type": "InlineCode", "__tag": 4051, "value": "build/" }, { "__type": "Text", "__tag": 4046, "value": " and a local install under " }, { "__type": "InlineCode", "__tag": 4051, "value": "build-install/" }, { "__type": "Text", "__tag": 4046, "value": " relative to the root of the repo, do " } ] }, { "__type": "Code", "__tag": 4050, "value": "meson setup build --prefix=$PWD/build-install", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To then run the compile stage of the build, do " } ] }, { "__type": "Code", "__tag": 4050, "value": "ninja -C build", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the command above, " }, { "__type": "InlineCode", "__tag": 4051, "value": "-C" }, { "__type": "Text", "__tag": 4046, "value": " is followed by the name of the build directory. You can have multiple build directories at the same time. Meson is fully out-of-place, so those builds will not interfere with each other. You can for example have a GCC build, a Clang build and a debug build in different directories." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To then install SciPy into the prefix (" }, { "__type": "InlineCode", "__tag": 4051, "value": "build-install/" }, { "__type": "Text", "__tag": 4046, "value": " here, but note that that's just an arbitrary name we picked here) " } ] }, { "__type": "Code", "__tag": 4050, "value": "meson install -C build", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It will then install to " }, { "__type": "InlineCode", "__tag": 4051, "value": "build-install/lib/python3.11/site-packages/scipy" }, { "__type": "Text", "__tag": 4046, "value": ", which is not on your Python path, so to add it do (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "again, this is for learning\npurposes, using ``PYTHONPATH`` explicitly is typically not the best idea" } ] }, { "__type": "Text", "__tag": 4046, "value": ") " } ] }, { "__type": "Code", "__tag": 4050, "value": "export PYTHONPATH=$PWD/build-install/lib/python3.11/site-packages/", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now we should be able to import " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy" }, { "__type": "Text", "__tag": 4046, "value": " and run the tests. Remembering that we need to move out of the root of the repo to ensure we pick up the package and not the local " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy/" }, { "__type": "Text", "__tag": 4046, "value": " source directory " } ] }, { "__type": "Code", "__tag": 4050, "value": "cd doc\npython -c \"from scipy import constants as s; s.test()\"", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The above runs the tests for a single module, " }, { "__type": "InlineCode", "__tag": 4051, "value": "constants" }, { "__type": "Text", "__tag": 4046, "value": ". Other ways of running the tests should also work, for example " } ] }, { "__type": "Code", "__tag": 4050, "value": "pytest --pyargs scipy", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The full test suite should pass, without any build warnings on Linux (with the GCC version for which " }, { "__type": "InlineCode", "__tag": 4051, "value": "-Werror" }, { "__type": "Text", "__tag": 4046, "value": " is enforced in CI at least) and with at most a moderate amount of warnings on other platforms." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Explanation of build stages" } ], "level": 1, "target": null } ], "local_refs": [] }