deploy: ba61e25

_sources/guide.rst.txt

@@ -0,0 +1,37 @@
+Instructor's guide
+==================
+
+Why we teach this lesson
+------------------------
+
+
+
+Intended learning outcomes
+--------------------------
+
+
+
+Timing
+------
+
+
+
+Preparing exercises
+-------------------
+
+e.g. what to do the day before to set up common repositories.
+
+
+
+Other practical aspects
+-----------------------
+
+
+
+Interesting questions you might get
+-----------------------------------
+
+
+
+Typical pitfalls
+----------------

_sources/index.rst.txt

@@ -0,0 +1,168 @@
+Introduction to CMake
+=====================
+
+
+CMake is a language-agnostic, cross-platform build tool and is nowadays the *de facto* standard, with large projects using it to reliably build, test, and deploy their codebases.
+
+CMake is not a build system itself, but it generates another system's build files.
+
+In this workshop, you will learn
+
+- Write a CMake build system for C/C++ and Fortran projects producing libraries and/or executables.
+- Run tests for your code with `CTest`.
+- Ensure your build system will work on different platforms.
+- (optional) Detect and use external dependencies in your project.
+- (optional) Safely and effectively build mixed-language projects (Python+C/C++, Python+Fortran, Fortran+C/C++)
+
+
+
+.. prereq::
+
+   Before attending this workshop, please make sure that you have access to a computer with a compiler for your favorite programming language and a recent version of CMake.
+
+   If you have access to a supercomputer (e.g. a `NAISS system <https://www.naiss.se/>`_) with a compute allocation you can use that during    the workshop. Any questions on how to use a particular HPC resource should be    directed to the appropriate support desk.
+
+   You can also use your own computer for this workshop, provided that it has the necessary tools installed.
+
+   - If you do not already have these installed, we recommend that you set up an isolated software environment using ``conda``.
+   - For Windows computers we recommend to use the **Windows Subsystem for Linux (WSL)**. Detailed instructions can be found on the :doc:`setup` page.
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   setup
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: The lesson
+
+   hello-cmake
+   cmake-syntax
+   hello-ctest
+   probing
+   targets
+   .. dependencies
+   .. fetch-content
+   .. python-bindings
+   tips-and-tricks
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Additional topics
+
+   .. environment
+   .. cxx-fortran
+
+
+.. csv-table::
+   :widths: auto
+   :delim: ;
+
+   30 min ; :doc:`hello-cmake`
+   40 min ; :doc:`cmake-syntax`
+   40 min ; :doc:`hello-ctest`
+   40 min ; :doc:`probing`
+   40 min ; :doc:`targets`
+   .. 30 min ; :doc:`dependencies`
+   .. 40 min ; :doc:`fetch-content`
+   .. 35 min ; :doc:`python-bindings`
+   20 min ; :doc:`tips-and-tricks`
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference
+
+   .. quick-reference
+   .. zbibliography
+   .. guide
+
+
+
+.. _learner-personas:
+
+
+
+Who is the course for?
+----------------------
+
+This course is for students, researchers, engineers, and programmers that have heard of `CMake <https://cmake.org/>`_ and want to learn how to use it effectively with projects they are working on.
+This course assumes no previous experience with `CMake <https://cmake.org/>`_. You will have to be familiar with the tools commonly used to build software in your compiled language of choice (C/C++ or Fortran).
+
+Specifically, this lesson assumes that participants have some prior experience with or knowledge of the following topics (but no expertise is required):
+
+- Compiling and linking executables and libraries.
+- Differences between shared and static libraries.
+- Automated testing.
+
+
+
+About this course
+-----------------
+
+This lesson material is originally developed by the `EuroCC National Competence Center Sweden (ENCCS) <https://enccs.se/>`_ and taught in the `CMake Workshop <https://enccs.github.io/cmake-workshop/>`_.
+Each lesson episode has clearly defined learning objectives and includes multiple exercises along with solutions, and is therefore also useful for self-learning.
+
+This material `Introduction to CMake <https://enccs.github.io/intro-cmake/>`_ was adapted from the material used for `CMake Workshop <https://enccs.github.io/cmake-workshop/>`_ and will be use for the `Build Systems Course and Hackathon <https://enccs.se/events/build-systems-course-and-hackathon-2024/>`_.
+
+The lesson material is licensed under `CC-BY-4.0 <https://creativecommons.org/licenses/by/4.0/>`_ and can be reused in any form (with appropriate credit) in other courses and workshops. Instructors who wish to teach this lesson can refer to the :doc:`guide` for practical advice.
+
+
+
+Outreach
+--------
+
+There are many free online resources regarding CMake:
+
+- The `CMake official documentation <https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html>`_.
+- The `CMake tutorial <https://cmake.org/cmake/help/v3.19/guide/tutorial/index.html#guide:CMake%20Tutorial>`_.
+- The `HEP Software Foundation <https://hsf-training.github.io/hsf-training-cmake-webpage/>`_ training course.
+- The `Building portable code with CMake <https://coderefinery.github.io/cmake/>`_ from the `CodeRefinery <https://coderefinery.org/>`_.
+
+
+You can also consult the following books:
+
+- **Professional CMake: A Practical Guide** by Craig Scott.
+- **CMake Cookbook** by Radovan Bast and Roberto Di Remigio. The accompanying repository is on `GitHub <https://github.com/dev-cafe/cmake-cookbook>`_
+
+
+
+Credits
+-------
+
+The lesson file structure and browsing layout is inspired by and derived from the `work <https://github.com/coderefinery/sphinx-lesson>`_ by `CodeRefinery <https://coderefinery.org/>`_ licensed under the `MIT license <http://opensource.org/licenses/mit-license.html>`_. We have copied and adapted most of their license text.
+
+
+
+Instructional Material
+^^^^^^^^^^^^^^^^^^^^^^
+
+All ENCCS instructional material is made available under the `Creative Commons Attribution license (CC-BY-4.0) <https://creativecommons.org/licenses/by/4.0/>`_. The following is a human-readable summary of (and not a substitute for) the `full legal text of the CC-BY-4.0 license <https://creativecommons.org/licenses/by/4.0/legalcode>`_. You are free:
+
+- to **share** - copy and redistribute the material in any medium or format;
+- to **adapt** - remix, transform, and build upon the material for any purpose, even commercially.
+
+
+The licensor cannot revoke these freedoms as long as you follow these license terms:
+
+- **Attribution** - You must give appropriate credit (mentioning that your work is derived from work that is Copyright (c) ENCCS and, where practical, linking to `<https://enccs.se>`_), provide a `link to the license <https://creativecommons.org/licenses/by/4.0/>`_, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+- **No additional restrictions** - You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. With the understanding that:
+
+	- You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+	- No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
+
+
+
+Software
+^^^^^^^^
+
+The code samples and exercises in this lesson were adapted from the GitHub repository for the `CMake Cookbook <https://github.com/dev-cafe/cmake-cookbook>`_.
+
+Except where otherwise noted, the example programs and other software provided by ENCCS are made available under the `OSI <http://opensource.org/>`_-approved `MIT license <http://opensource.org/licenses/mit-license.html>`_.
+

_sources/quick-reference.rst.txt

@@ -0,0 +1,2 @@
+Quick Reference
+===============

_static/_sphinx_javascript_frameworks_compat.js

@@ -0,0 +1,123 @@
+/* Compatability shim for jQuery and underscores.js.
+ *
+ * Copyright Sphinx contributors
+ * Released under the two clause BSD licence
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}