Skip to content

Add documentation on build systems #5015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scheibelp merged 28 commits into from
Jul 17, 2018
Merged

Add documentation on build systems #5015

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
080ce4c
Add documentation on the MakefilePackage build system
adamjstewart Aug 7, 2017
719eccb
Add documentation on the QMakePackage build system
adamjstewart Aug 7, 2017
ae99a9e
Add placeholders for RubyPackage and IntelPackage
adamjstewart Aug 7, 2017
ab72f1e
Code blocks must have language specifier
adamjstewart Aug 8, 2017
7fb874d
Add documentation on the SConsPackage build system
adamjstewart Aug 8, 2017
e6e0d4a
Add table of contents
adamjstewart Aug 8, 2017
492d5f1
Add documentation on the WafPackage build system
adamjstewart Aug 8, 2017
bc10a22
Add documentation on the RPackage build system
adamjstewart Aug 9, 2017
256cc2b
Add documentation on the PythonPackage build system
adamjstewart Aug 10, 2017
959131d
Add external documentation links to all build systems
adamjstewart Aug 10, 2017
1b8b140
Add documentation on the PerlPackage build system
adamjstewart Aug 11, 2017
9efd47e
Add documentation for OctavePackage and CudaPackage
davydden Jan 3, 2018
6f94d93
improve docs for OctavePackage and CudaPackage
davydden Jan 3, 2018
08d1596
Fix grammar in MakefilePackage docs
adamjstewart May 14, 2018
ec880ec
Update --test flag in QMakePackage docs
adamjstewart May 14, 2018
30744fd
Update PythonPackage docs for new PyPI website
adamjstewart May 14, 2018
aaedf9b
Add external documentation link to OctavePackage docs
adamjstewart May 14, 2018
92d76b9
Update to new spack/spack repo name
adamjstewart May 14, 2018
db1f23c
Add documentation on AutotoolsPackage
adamjstewart May 15, 2018
a0155a0
Move custom build systems docs to the end
adamjstewart May 15, 2018
c02e959
Add CMakePackage docs
adamjstewart May 15, 2018
4a03e68
Add instructions for writing custom build systems
adamjstewart May 16, 2018
c45c8bc
First round of code review courtesy of @citibeth
adamjstewart May 17, 2018
99e20d9
Reorder build systems alphabetically
adamjstewart May 28, 2018
88c2638
Add attribution to Automake/Autoconf diagram
adamjstewart May 28, 2018
6d740d9
Add links to packages, miscellaneous enhancements
adamjstewart May 28, 2018
f363fd4
Clarify a few points, better citation, and grammar fix
adamjstewart Jun 27, 2018
abe403c
Address @tgamblin's comments
adamjstewart Jul 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 83 additions & 0 deletions lib/spack/docs/build_systems.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@

.. _build-systems:

=============
Build Systems
=============

Spack defines a number of classes which understand how to use common
`build systems <https://en.wikipedia.org/wiki/List_of_build_automation_software>`_
(Makefiles, CMake, etc.). Spack package definitions can inherit these
classes in order to streamline their builds.

This guide provides information specific to each particular build system.
It assumes that you've read the :ref:`packaging-guide` and expands
on these ideas for each distinct build system that Spack supports:

.. toctree::
:maxdepth: 1
:caption: Make-based

build_systems/makefilepackage

.. toctree::
:maxdepth: 1
:caption: Make-incompatible

build_systems/sconspackage
build_systems/wafpackage

.. toctree::
:maxdepth: 1
:caption: Build-script generation

build_systems/autotoolspackage
build_systems/cmakepackage
build_systems/qmakepackage

.. toctree::
:maxdepth: 1
:caption: Language-specific

build_systems/octavepackage
build_systems/perlpackage
build_systems/pythonpackage
build_systems/rpackage
build_systems/rubypackage

.. toctree::
:maxdepth: 1
:caption: Other

build_systems/cudapackage
build_systems/intelpackage
build_systems/custompackage

For reference, the :py:mod:`Build System API docs <spack.build_systems>`
provide a list of build systems and methods/attributes that can be
overridden. If you are curious about the implementation of a particular
build system, you can view the source code by running:

.. code-block:: console

$ spack edit --build-system autotools
Copy link
Copy Markdown
Member

@citibeth citibeth May 16, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm really dubious on the value of this command. It's more work for me to remember the special spack edit command than the general approach of finding the file in the Spack directory. Why don't we just tell users where the build system .py files are?

In addition... I edit remotely, so spack edit will never work for me.

Copy link
Copy Markdown
Member Author

@adamjstewart adamjstewart May 16, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's not reopen old wounds. This was settled on in #2865. You might not find it useful, but I probably used it hundreds of times while writing these docs. I don't know if I could survive without it.

Copy link
Copy Markdown
Member

@citibeth citibeth May 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please just provide appropriate alternatives. Tell people where the file is located in case they want to edit it themselves, give URLs to GItHub, etc.



This will open up the ``AutotoolsPackage`` definition in your favorite
editor. In addition, if you are working with a less common build system
like QMake, SCons, or Waf, it may be useful to see examples of other
packages. You can quickly find examples by running:

.. code-block:: console

$ cd var/spack/repos/builtin/packages
$ grep -l QMakePackage */package.py


You can then view these packages with ``spack edit``.
Copy link
Copy Markdown
Member

@citibeth citibeth May 16, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or with less <pacakge>/package.py

Copy link
Copy Markdown
Member Author

@adamjstewart adamjstewart May 16, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

$ spack edit foo

is fewer characters than

$ less ~/spack/var/spack/repos/builtin/packages/foo/package.py

so I went with the former.

Copy link
Copy Markdown
Member

@citibeth citibeth May 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again... people need to know where the files really are if they aren't going to see Spack as magic.

@tgamblin I would also LOVE to shorten some of these needlessly long paths in Spack. I understand the rationale of mirroring a Unix filesystem. But I don't see how it helps us, or where it is useful. What I DO see is unnecessarily long paths, along with having to remember which bits of Spack end up in /var vs /opt vs/ share vs /lib. It all seems so arbitrary and NOT user friendly.

At the very least, I would like symlink shortcuts to commonly used directories. I asked for this before and the idea was rejected. But I still want them, and I still add them routinely to my branches.


This guide is intended to supplement the
:py:mod:`Build System API docs <spack.build_systems>` with examples of
how to override commonly used methods. It also provides rules of thumb
and suggestions for package developers who are unfamiliar with a
particular build system.
Loading