summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--lib/spack/docs/module_file_generation.svg989
-rw-r--r--lib/spack/docs/tutorial_modules.rst1283
-rw-r--r--lib/spack/docs/workflows.rst2
-rw-r--r--share/spack/docs/docker/module-file-tutorial/Dockerfile52
-rw-r--r--share/spack/docs/docker/module-file-tutorial/packages.yaml9
-rw-r--r--share/spack/docs/docker/module-file-tutorial/spack.sh8
6 files changed, 1980 insertions, 363 deletions
diff --git a/lib/spack/docs/module_file_generation.svg b/lib/spack/docs/module_file_generation.svg
new file mode 100644
index 0000000000..72affd43d6
--- /dev/null
+++ b/lib/spack/docs/module_file_generation.svg
@@ -0,0 +1,989 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="682"
+ height="382"
+ id="svg3341"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="module_file_generation.svg">
+ <metadata
+ id="metadata3657">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1920"
+ inkscape:window-height="1134"
+ id="namedview3655"
+ showgrid="false"
+ inkscape:zoom="2.0073314"
+ inkscape:cx="341"
+ inkscape:cy="191"
+ inkscape:window-x="1920"
+ inkscape:window-y="27"
+ inkscape:window-maximized="1"
+ inkscape:current-layer="g3345" />
+ <defs
+ id="defs3343" />
+ <g
+ inkscape:groupmode="layer"
+ id="layer1"
+ inkscape:label="Background">
+ <rect
+ style="fill:none;stroke:#ff0000;stroke-width:1.40437257;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:8.42623582, 8.42623582;stroke-dashoffset:0"
+ id="rect3844"
+ width="442.15341"
+ height="375.15021"
+ x="18.745768"
+ y="3.2206354" />
+ <rect
+ style="fill:none;stroke:#0000ff;stroke-width:1.50000000000000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:9, 9;stroke-dashoffset:0"
+ id="rect3844-6"
+ width="175.74904"
+ height="179.83459"
+ x="486.96402"
+ y="179.3212" />
+ </g>
+ <g
+ id="g3345">
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3347">
+ <rect
+ fill="#C0C0C0"
+ stroke="none"
+ x="297"
+ y="231"
+ width="198"
+ height="104"
+ opacity="0.2"
+ id="rect3349" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3351">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="290"
+ y="224"
+ width="198"
+ height="104"
+ id="rect3353" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3355">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 290 224 L 488 224 L 488 328 L 290 328 L 290 224 Z Z"
+ stroke-miterlimit="10"
+ id="path3357" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3359">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="280"
+ y="231"
+ width="20"
+ height="10"
+ id="rect3361" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3363">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 280 231 L 300 231 L 300 241 L 280 241 L 280 231 Z Z"
+ stroke-miterlimit="10"
+ id="path3365" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3367">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="280"
+ y="251"
+ width="20"
+ height="10"
+ id="rect3369" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3371">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 280 251 L 300 251 L 300 261 L 280 261 L 280 251 Z Z"
+ stroke-miterlimit="10"
+ id="path3373" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3375">
+ <g
+ id="g3377">
+ <path
+ fill="none"
+ stroke="none"
+ id="path3379" />
+ <text
+ fill="#000000"
+ stroke="none"
+ font-family="Arial"
+ font-size="13px"
+ font-style="normal"
+ font-weight="bold"
+ text-decoration="none"
+ x="343"
+ y="243.5"
+ id="text3381">Configuration files</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3383">
+ <rect
+ fill="#C0C0C0"
+ stroke="none"
+ x="327"
+ y="263"
+ width="98"
+ height="24"
+ opacity="0.2"
+ id="rect3385" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3387">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="320"
+ y="256"
+ width="98"
+ height="24"
+ id="rect3389" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3391">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 320 256 L 418 256 L 418 280 L 320 280 L 320 256 Z Z"
+ stroke-miterlimit="10"
+ id="path3393" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3395">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="320"
+ y="256"
+ width="98"
+ height="24"
+ id="rect3397" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3399">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 320 256 L 418 256 L 418 280 L 320 280 L 320 256 Z Z"
+ stroke-miterlimit="10"
+ id="path3401" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3403">
+ <g
+ id="g3405"
+ transform="translate(-2.8259277,-4.138916)">
+ <path
+ id="path3407"
+ d=""
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:none" />
+ <text
+ font-size="13px"
+ font-style="normal"
+ font-weight="bold"
+ text-decoration="none"
+ x="328.5"
+ y="275.5"
+ id="text3409"
+ style="font-size:13px;font-style:normal;font-weight:bold;text-decoration:none;fill:#000000;stroke:none;font-family:Arial">modules.yaml</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3411">
+ <rect
+ fill="#C0C0C0"
+ stroke="none"
+ x="335"
+ y="295"
+ width="83"
+ height="24"
+ opacity="0.2"
+ id="rect3413" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3415">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="328"
+ y="288"
+ width="83"
+ height="24"
+ id="rect3417" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3419">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 328 288 L 411 288 L 411 312 L 328 312 L 328 288 Z Z"
+ stroke-miterlimit="10"
+ id="path3421" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3423">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="328"
+ y="288"
+ width="83"
+ height="24"
+ id="rect3425" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3427">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 328 288 L 411 288 L 411 312 L 328 312 L 328 288 Z Z"
+ stroke-miterlimit="10"
+ id="path3429" />
+ </g>
+ <g
+ transform="translate(-248.92773,-218.16748)"
+ id="g3431">
+ <g
+ id="g3433">
+ <path
+ id="path3435"
+ d=""
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:none" />
+ <text
+ font-size="13px"
+ font-style="normal"
+ font-weight="bold"
+ text-decoration="none"
+ x="336.5"
+ y="307.5"
+ id="text3437"
+ style="font-size:13px;font-style:normal;font-weight:bold;text-decoration:none;fill:#000000;stroke:none;font-family:Arial">config.yaml</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3439">
+ <rect
+ fill="#C0C0C0"
+ stroke="none"
+ x="489"
+ y="407"
+ width="198"
+ height="72"
+ opacity="0.2"
+ id="rect3441" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3443">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="482"
+ y="400"
+ width="198"
+ height="72"
+ id="rect3445" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3447">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 482 400 L 680 400 L 680 472 L 482 472 L 482 400 Z Z"
+ stroke-miterlimit="10"
+ id="path3449" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3451">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="472"
+ y="407"
+ width="20"
+ height="10"
+ id="rect3453" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3455">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 472 407 L 492 407 L 492 417 L 472 417 L 472 407 Z Z"
+ stroke-miterlimit="10"
+ id="path3457" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3459">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="472"
+ y="427"
+ width="20"
+ height="10"
+ id="rect3461" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3463">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 472 427 L 492 427 L 492 437 L 472 437 L 472 427 Z Z"
+ stroke-miterlimit="10"
+ id="path3465" />
+ </g>
+ <g
+ transform="translate(-255.37842,-194.16748)"
+ id="g3467">
+ <g
+ id="g3469">
+ <path
+ id="path3471"
+ d=""
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:none" />
+ <text
+ font-size="13px"
+ font-style="normal"
+ font-weight="bold"
+ text-decoration="none"
+ x="528"
+ y="419.5"
+ id="text3473"
+ style="font-size:13px;font-style:normal;font-weight:bold;text-decoration:none;fill:#000000;stroke:none;font-family:Arial">Module subpackage</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3475">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 369 313 L 368 440 L 471 438"
+ stroke-miterlimit="10"
+ stroke-dasharray="3"
+ id="path3477" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3479">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 460.9209632639215 442.4060207072573 L 471 438 L 460.7575176559406 433.98857189624056"
+ stroke-miterlimit="10"
+ id="path3481" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3483">
+ <path
+ fill="#ffffff"
+ stroke="none"
+ d="M 256 448 L 381 448 L 391 458 L 391 496 L 256 496 L 256 448"
+ id="path3485" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3487">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 256 448 L 381 448 L 391 458 L 391 496 L 256 496 L 256 448 L 256 448"
+ stroke-miterlimit="10"
+ id="path3489" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3491">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 381 448 L 381 458 L 391 458 L 381 448"
+ stroke-miterlimit="10"
+ id="path3493" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3495">
+ <g
+ id="g3497">
+ <path
+ fill="none"
+ stroke="none"
+ id="path3499" />
+ <text
+ fill="#000000"
+ stroke="none"
+ font-family="Arial"
+ font-size="13px"
+ font-style="normal"
+ font-weight="normal"
+ text-decoration="none"
+ x="261"
+ y="466"
+ id="text3501">template directory</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3503">
+ <g
+ id="g3505">
+ <path
+ fill="none"
+ stroke="none"
+ id="path3507" />
+ <text
+ fill="#000000"
+ stroke="none"
+ font-family="Arial"
+ font-size="13px"
+ font-style="normal"
+ font-weight="normal"
+ text-decoration="none"
+ x="261"
+ y="481"
+ id="text3509">module file directory</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3511">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 419 439 L 393 448"
+ stroke-miterlimit="10"
+ stroke-dasharray="3"
+ id="path3513" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3515">
+ <path
+ d="M 419,267 576.40856,267.26845 576,399"
+ stroke-miterlimit="10"
+ id="path3517"
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:#000000;stroke-miterlimit:10;stroke-dasharray:3"
+ sodipodi:nodetypes="ccc" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3519">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 571.790482243984 388.83732514237585 L 576 399 L 580.209517756016 388.83732514237585"
+ stroke-miterlimit="10"
+ id="path3521" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3523">
+ <path
+ fill="#ffffff"
+ stroke="none"
+ d="M 600 296 L 737 296 L 747 306 L 747 344 L 600 344 L 600 296"
+ id="path3525" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3527">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 600 296 L 737 296 L 747 306 L 747 344 L 600 344 L 600 296 L 600 296"
+ stroke-miterlimit="10"
+ id="path3529" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3531">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 737 296 L 737 306 L 747 306 L 737 296"
+ stroke-miterlimit="10"
+ id="path3533" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3535">
+ <g
+ id="g3537">
+ <path
+ fill="none"
+ stroke="none"
+ id="path3539" />
+ <text
+ fill="#000000"
+ stroke="none"
+ font-family="Arial"
+ font-size="13px"
+ font-style="normal"
+ font-weight="normal"
+ text-decoration="none"
+ x="605"
+ y="314"
+ id="text3541">content customization</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3543">
+ <g
+ id="g3545">
+ <path
+ fill="none"
+ stroke="none"
+ id="path3547" />
+ <text
+ fill="#000000"
+ stroke="none"
+ font-family="Arial"
+ font-size="13px"
+ font-style="normal"
+ font-weight="normal"
+ text-decoration="none"
+ x="605"
+ y="329"
+ id="text3549">layout customization</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3551">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 576 331 L 599 328"
+ stroke-miterlimit="10"
+ stroke-dasharray="3"
+ id="path3553" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3555">
+ <rect
+ fill="#C0C0C0"
+ stroke="none"
+ x="801"
+ y="415"
+ width="99"
+ height="44"
+ opacity="0.2"
+ id="rect3557" />
+ </g>
+ <g
+ transform="translate(-246,-210)"
+ id="g3559">
+ <rect
+ x="794"
+ y="408"
+ width="99"
+ height="44"
+ id="rect3561"
+ style="fill:#ffffff;stroke:none" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3563">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 794 408 L 893 408 L 893 452 L 794 452 L 794 408 Z Z"
+ stroke-miterlimit="10"
+ id="path3565" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3567">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="784"
+ y="415"
+ width="20"
+ height="10"
+ id="rect3569" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3571">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 784 415 L 804 415 L 804 425 L 784 425 L 784 415 Z Z"
+ stroke-miterlimit="10"
+ id="path3573" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3575">
+ <rect
+ fill="#ffffff"
+ stroke="none"
+ x="784"
+ y="435"
+ width="20"
+ height="10"
+ id="rect3577" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3579">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 784 435 L 804 435 L 804 445 L 784 445 L 784 435 Z Z"
+ stroke-miterlimit="10"
+ id="path3581" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3583">
+ <g
+ id="g3585"
+ transform="translate(-6.7685547,5.861084)">
+ <path
+ id="path3587"
+ d=""
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:none" />
+ <text
+ font-size="13px"
+ font-style="normal"
+ font-weight="bold"
+ text-decoration="none"
+ x="832"
+ y="427.5"
+ id="text3589"
+ style="font-size:13px;font-style:normal;font-weight:bold;text-decoration:none;fill:#000000;stroke:none;font-family:Arial">Jinja2</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3591">
+ <path
+ fill="#C0C0C0"
+ stroke="none"
+ d="M 568.9 519 L 596.34 519 L 608.1 530.76 L 608.1 568 L 568.9 568"
+ opacity="0.2"
+ id="path3593" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3595">
+ <path
+ fill="#ffffff"
+ stroke="none"
+ d="M 561.9 512 L 589.34 512 L 601.1 523.76 L 601.1 561 L 561.9 561"
+ id="path3597" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3599">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 561.9 512 L 589.34 512 L 601.1 523.76 L 601.1 561 L 561.9 561 L 561.9 512"
+ stroke-miterlimit="10"
+ id="path3601" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3603">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 589.34 512 L 589.34 523.76 L 601.1 523.76 L 589.34 512"
+ stroke-miterlimit="10"
+ id="path3605" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3607">
+ <g
+ id="g3609">
+ <path
+ fill="none"
+ stroke="none"
+ id="path3611" />
+ <text
+ fill="#000000"
+ stroke="none"
+ font-family="Arial"
+ font-size="13px"
+ font-style="normal"
+ font-weight="bold"
+ text-decoration="none"
+ x="551.5"
+ y="580.5"
+ id="text3613">Templates</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3615">
+ <path
+ d="M 620,549 836.73155,549.54866 838,453"
+ stroke-miterlimit="10"
+ id="path3617"
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:#000000;stroke-miterlimit:10;stroke-dasharray:3"
+ sodipodi:nodetypes="ccc" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3619">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 842.4139237018308 463.0755782739462 L 838 453 L 833.9966056593214 463.2456251030878"
+ stroke-miterlimit="10"
+ id="path3621" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3623">
+ <path
+ d="M 680.18289,431.54866 783,431"
+ stroke-miterlimit="10"
+ id="path3625"
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:#000000;stroke-miterlimit:10;stroke-dasharray:3"
+ sodipodi:nodetypes="cc" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3627">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 772.9654737429415 435.5064712133113 L 783 431 L 772.7179620834851 427.0910747917938"
+ stroke-miterlimit="10"
+ id="path3629" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3631">
+ <path
+ fill="#C0C0C0"
+ stroke="none"
+ d="M 862.4 247 L 889.84 247 L 901.6 258.76 L 901.6 296 L 862.4 296"
+ opacity="0.2"
+ id="path3633" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3635">
+ <path
+ fill="#ffffff"
+ stroke="none"
+ d="M 855.4 240 L 882.84 240 L 894.6 251.76000000000002 L 894.6 289 L 855.4 289"
+ id="path3637" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3639">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 855.4 240 L 882.84 240 L 894.6 251.76000000000002 L 894.6 289 L 855.4 289 L 855.4 240"
+ stroke-miterlimit="10"
+ id="path3641" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3643">
+ <path
+ fill="none"
+ stroke="#000000"
+ d="M 882.84 240 L 882.84 251.76000000000002 L 894.6 251.76000000000002 L 882.84 240"
+ stroke-miterlimit="10"
+ id="path3645" />
+ </g>
+ <g
+ transform="translate(-246,-214) scale(1,1)"
+ id="g3647">
+ <g
+ id="g3649">
+ <path
+ fill="none"
+ stroke="none"
+ id="path3651" />
+ <text
+ fill="#000000"
+ stroke="none"
+ font-family="Arial"
+ font-size="13px"
+ font-style="normal"
+ font-weight="bold"
+ text-decoration="none"
+ x="840.5"
+ y="308.5"
+ id="text3653">Module files</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-261.34866,-222.82727)"
+ id="g3635-8">
+ <path
+ style="fill:#ffffff;stroke:none"
+ inkscape:connector-curvature="0"
+ d="m 855.4,240 27.44,0 11.76,11.76 0,37.24 -39.2,0"
+ id="path3637-9" />
+ </g>
+ <g
+ transform="translate(-261.34866,-222.82727)"
+ id="g3639-7">
+ <path
+ style="fill:none;stroke:#000000;stroke-miterlimit:10"
+ inkscape:connector-curvature="0"
+ d="m 855.4,240 27.44,0 11.76,11.76 0,37.24 -39.2,0 0,-49"
+ stroke-miterlimit="10"
+ id="path3641-3" />
+ </g>
+ <g
+ transform="translate(-261.34866,-222.82727)"
+ id="g3643-6">
+ <path
+ style="fill:none;stroke:#000000;stroke-miterlimit:10"
+ inkscape:connector-curvature="0"
+ d="m 882.84,240 0,11.76 11.76,0 L 882.84,240"
+ stroke-miterlimit="10"
+ id="path3645-1" />
+ </g>
+ <g
+ transform="translate(-278.09946,-233.44973)"
+ id="g3635-84">
+ <path
+ style="fill:#ffffff;stroke:none"
+ inkscape:connector-curvature="0"
+ d="m 855.4,240 27.44,0 11.76,11.76 0,37.24 -39.2,0"
+ id="path3637-5" />
+ </g>
+ <g
+ transform="translate(-278.09946,-233.44973)"
+ id="g3639-0">
+ <path
+ style="fill:none;stroke:#000000;stroke-miterlimit:10"
+ inkscape:connector-curvature="0"
+ d="m 855.4,240 27.44,0 11.76,11.76 0,37.24 -39.2,0 0,-49"
+ stroke-miterlimit="10"
+ id="path3641-36" />
+ </g>
+ <g
+ transform="translate(-278.09946,-233.44973)"
+ id="g3643-1">
+ <path
+ style="fill:none;stroke:#000000;stroke-miterlimit:10"
+ inkscape:connector-curvature="0"
+ d="m 882.84,240 0,11.76 11.76,0 L 882.84,240"
+ stroke-miterlimit="10"
+ id="path3645-0" />
+ </g>
+ <g
+ transform="translate(-27.431351,-208.3001)"
+ id="g3375-6" />
+ <g
+ id="g4709"
+ transform="matrix(1,0,0,0.81117898,54.337968,31.640263)">
+ <g
+ id="g3623-5"
+ transform="matrix(0,-1,1,0,121.9107,875.37876)">
+ <path
+ sodipodi:nodetypes="cc"
+ style="fill:none;stroke:#000000;stroke-miterlimit:10;stroke-dasharray:3"
+ inkscape:connector-curvature="0"
+ id="path3625-4"
+ stroke-miterlimit="10"
+ d="M 680.18289,431.54866 783,431" />
+ </g>
+ <g
+ id="g3627-7"
+ transform="matrix(0,-1,1,0,121.98695,871.00978)">
+ <path
+ id="path3629-6"
+ stroke-miterlimit="10"
+ d="M 772.96547,435.50647 783,431 772.71796,427.09107"
+ inkscape:connector-curvature="0"
+ style="fill:none;stroke:#000000;stroke-miterlimit:10" />
+ </g>
+ </g>
+ </g>
+</svg>
diff --git a/lib/spack/docs/tutorial_modules.rst b/lib/spack/docs/tutorial_modules.rst
index d43e869bfc..21e1e5e886 100644
--- a/lib/spack/docs/tutorial_modules.rst
+++ b/lib/spack/docs/tutorial_modules.rst
@@ -1,52 +1,259 @@
.. _modules-tutorial:
-=============================
-Module Configuration Tutorial
-=============================
+============
+Module Files
+============
+
+In this tutorial, we'll introduce a few concepts that are fundamental
+to the generation of module files with Spack, and we'll guide you through
+the customization of both module files content and their layout on disk. In the end you
+should have a clear understanding of:
+
+ * What are module files and how they work
+ * How Spack generates them
+ * Which commands are available to ease their maintenance
+ * How it is possible to customize them in all aspects
-This tutorial will guide you through the customization of both
-content and naming of module files generated by Spack.
+.. _module_file_tutorial_overview:
-Starting from the default Spack settings you will add an increasing
-number of directives to the ``modules.yaml`` configuration file to
-satisfy a number of constraints that mimic those that you may encounter
-in a typical production environment at HPC sites.
+-------------------
+Modules at a glance
+-------------------
-Even though the focus will be for the most part on customizing
-TCL non-hierarchical module files, everything
-you'll see applies also to other kinds of module files generated by Spack.
+Let's start by summarizing what module files are and how you can use
+them to modify your environment. The idea is to give enough information so that
+people without any previous exposure to them will be able to follow the tutorial
+later on. We'll also give a high-level view of how module files are generated
+in Spack. If you are already familiar with these topics you can quickly skim
+through this section or move directly to :ref:`module_file_tutorial_prerequisites`.
-The generation of Lua hierarchical
-module files will be addressed at the end of the tutorial,
-and you'll see that with minor modifications
-to an existing ``modules.yaml`` written for TCL
-non-hierarchical modules you'll get almost
-for free the possibility to try a hierarchical layout.
+.. _module_file_tutorial_what_are_modules:
-Let's start!
+^^^^^^^^^^^^^^^^^^^^^^
+What are module files?
+^^^^^^^^^^^^^^^^^^^^^^
+
+Module files are an easy way to modify your environment in a controlled manner
+during a shell session. In general, they contain the information needed to run an
+application or use a library, and they work in conjunction with a tool that
+interprets them.
+Typical module files instruct this tool to modify the environment variables when a
+module file is loaded:
+
+ .. code-block:: console
+
+ $ module show zlib
+ -------------------------------------------------------------------
+ /home/mculpo/PycharmProjects/spack/share/spack/modules/linux-ubuntu14.04-x86_64/zlib/1.2.11-gcc-7.2.0-linux-ubuntu14.04-x86_64-co2px3k:
+
+ module-whatis A free, general-purpose, legally unencumbered lossless data-compression library.
+ prepend-path MANPATH /home/mculpo/PycharmProjects/spack/opt/spack/linux-ubuntu14.04-x86_64/gcc-7.2.0/zlib-1.2.11-co2px3k53m76lm6tofylh2mur2hnicux/share/man
+ prepend-path LIBRARY_PATH /home/mculpo/PycharmProjects/spack/opt/spack/linux-ubuntu14.04-x86_64/gcc-7.2.0/zlib-1.2.11-co2px3k53m76lm6tofylh2mur2hnicux/lib
+ prepend-path LD_LIBRARY_PATH /home/mculpo/PycharmProjects/spack/opt/spack/linux-ubuntu14.04-x86_64/gcc-7.2.0/zlib-1.2.11-co2px3k53m76lm6tofylh2mur2hnicux/lib
+ prepend-path CPATH /home/mculpo/PycharmProjects/spack/opt/spack/linux-ubuntu14.04-x86_64/gcc-7.2.0/zlib-1.2.11-co2px3k53m76lm6tofylh2mur2hnicux/include
+ prepend-path PKG_CONFIG_PATH /home/mculpo/PycharmProjects/spack/opt/spack/linux-ubuntu14.04-x86_64/gcc-7.2.0/zlib-1.2.11-co2px3k53m76lm6tofylh2mur2hnicux/lib/pkgconfig
+ prepend-path CMAKE_PREFIX_PATH /home/mculpo/PycharmProjects/spack/opt/spack/linux-ubuntu14.04-x86_64/gcc-7.2.0/zlib-1.2.11-co2px3k53m76lm6tofylh2mur2hnicux/
+ -------------------------------------------------------------------
+
+ $ echo $LD_LIBRARY_PATH
+
+ $ module load zlib
+ $ echo $LD_LIBRARY_PATH
+ /home/mculpo/PycharmProjects/spack/opt/spack/linux-ubuntu14.04-x86_64/gcc-7.2.0/zlib-1.2.11-co2px3k53m76lm6tofylh2mur2hnicux/lib
+
+and to undo the modifications when the same module file is unloaded:
+
+ .. code-block:: console
+
+ $ module unload zlib
+ $ echo $LD_LIBRARY_PATH
+
+ $
+
+Different formats exist for module files, and different tools
+provide various levels of support for them. Spack can natively generate:
+
+1. Non-hierarchical module files written in TCL
+2. Hierarchical module files written in Lua
+
+and can build `environment-modules <http://modules.sourceforge.net/>`_
+and `lmod <http://lmod.readthedocs.io/en/latest>`_ as support tools.
+Which of the formats or tools best suits one's needs depends on each particular
+use-case. For the sake of illustration, we'll be working on
+both formats using ``lmod``.
+
+.. seealso::
+ Environment modules
+ This is the original tool that provided modules support. Its first
+ version was coded in C in the early '90s and was later substituted by a version
+ completely coded in TCL - the one Spack is distributing. More details on
+ its features are given in the `homepage of the project <http://modules.sourceforge.net/>`_
+ or in its `github page <https://github.com/cea-hpc/modules>`_. The tool is able to
+ interpret the non-hierarchical TCL modulefiles written by Spack.
+
+ Lmod
+ Lmod is a module system written in Lua, designed to easily handle hierarchies of
+ module files. It's a drop-in replacement of Environment Modules and works with
+ both of the module file formats generated by Spack.
+ Despite being fully compatible with Environment Modules there are many features that
+ are unique to Lmod. These features are either
+ `targeted towards safety <http://lmod.readthedocs.io/en/latest/010_user.html#safety-features>`_
+ or meant to
+ `extend the module system functionality <http://lmod.readthedocs.io/en/latest/010_user.html#module-hierarchy>`_.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+How do we generate module files?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before we dive into the hands-on sections it's worth spending a couple of words to explain how
+module files are generated by Spack. The following diagram provides a high-level view
+of the process:
+
+
+.. image:: module_file_generation.*
+
+The red dashed line above represents Spack's boundaries, the blue one Spack's dependencies [#f1]_.
+Module files are generated by combining:
+
+ * the configuration details in ``config.yaml`` and ``modules.yaml``
+ * the information contained in Spack packages (and processed by the module subpackage)
+ * a set of template files
+
+with `Jinja2 <http://jinja.pocoo.org/docs/2.9/>`_, an external template engine
+that stamps out each particular module file. As Spack serves very diverse needs
+this process has many points of customization, and we'll explore most of
+them in the next sections.
+
+.. [#f1] Spack vendors its dependencies! This means that Spack comes with a copy of
+ each one of its dependencies, including ``Jinja2``, and is already configured to use them.
.. _module_file_tutorial_prerequisites:
--------------
-Prerequisites
--------------
+----------------------
+Setup for the tutorial
+----------------------
-Before proceeding further ensure:
+In order to showcase the capabilities of Spack's module file generation, we need
+a representative set of software to work with. This set must include different
+flavors of the same packages installed alongside each other and some
+:ref:`external packages <sec-external-packages>`.
-- you have LMod or Environment Modules available
-- have :ref:`shell support <shell-support>` activated in Spack
+The purpose of this setup is not to make our life harder but to demonstrate
+how Spack can help with similar situations, as they will happen on real HPC clusters.
+For instance, it's often preferable for Spack to use vendor-provided MPI
+implementations than to build one itself.
-If you need to install Lmod or Environment module you can refer
-to the documentation :ref:`here <InstallEnvironmentModules>`.
+The best way to follow along is to use a Docker image, which comes
+with Spack and all the software used in the following parts already
+pre-installed. If you want to proceed this way, read :ref:`module_file_tutorial_use_docker`.
+If you don't have Docker installed or for any other reason you
+prefer to work locally, follow instead :ref:`module_file_tutorial_work_locally`
+to know how to clone Spack and install the software.
+Be aware that the set-up will take longer and that the details of the snippets
+below assume the Docker image and may need changes to work in your particular
+environment.
+
+.. _module_file_tutorial_use_docker:
^^^^^^^^^^^^^^^^^^
-Add a new compiler
+Use a Docker image
^^^^^^^^^^^^^^^^^^
-Spack automatically scans the environment to search for available
-compilers on first use. On Ubuntu 14.04, a fresh clone will show
-something like this:
+The fastest way to set-up your environment is to :ref:`use a Docker image <workflow_create_docker_image>`:
+
+.. code-block:: console
+
+ $ docker pull alalazo/spack:module_tutorial
+ $ docker run --rm -h module-file-tutorial -it alalazo/spack:module_tutorial
+ root@module-file-tutorial:/#
+
+If you arrived at this point you should be ready to start, as all the software needed is
+pre-installed in the image:
+
+.. code-block:: console
+
+ root@module-file-tutorial:/# which spack
+ /usr/local/bin/spack
+ root@module-file-tutorial:/# spack find
+ ==> 46 installed packages.
+ -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+ autoconf@2.69 gcc@7.2.0 git@2.9.4 isl@0.18 libtool@2.4.6 lua@5.3.4 lua-luaposix@33.4.0 mpc@1.0.3 ncurses@6.0 pkg-config@0.29.2 tcl@8.6.6
+ automake@1.15.1 gdbm@1.13 gmp@6.1.2 libsigsegv@2.11 lmod@7.7 lua-luafilesystem@1_6_3 m4@1.4.18 mpfr@3.1.5 perl@5.24.1 readline@7.0 zlib@1.2.11
+
+ -- linux-ubuntu16.04-x86_64 / gcc@7.2.0 -------------------------
+ bzip2@1.0.6 ncurses@6.0 netlib-scalapack@2.0.2 openblas@0.2.20 pkg-config@0.29.2 py-packaging@16.8 py-setuptools@35.0.2 readline@7.0
+ cmake@3.9.4 netlib-lapack@3.6.1 netlib-scalapack@2.0.2 openmpi@1.10.2 py-appdirs@1.4.3 py-pyparsing@2.2.0 py-six@1.10.0 sqlite@3.20.0
+ mpich@3.2 netlib-scalapack@2.0.2 netlib-scalapack@2.0.2 openssl@1.0.2k py-numpy@1.13.1 py-scipy@0.19.1 python@2.7.14 zlib@1.2.11
+
+Go to :ref:`module_file_tutorial_non_hierarchical` to proceed with the tutorial.
+
+.. note::
+ Dockerfile for this image
+ Those of you that want to build a similar container themselves can find the
+ ``Dockerfile`` and the other resources in Spack's ``share/spack/docs/docker``
+ folder.
+
+.. _module_file_tutorial_work_locally:
+
+^^^^^^^^^^^^^^^^^^^^^^
+Work in a local folder
+^^^^^^^^^^^^^^^^^^^^^^
+
+If you don't feel like using a container, you can set-up your environment
+locally. Let's start by cloning the Spack repository and moving to the directory
+where it was checked out:
+
+.. code-block:: console
+
+ $ git clone https://github.com/spack/spack.git
+ $ cd spack
+
+From here we'll be building the required stack of software.
+
+"""""""""""""""""""
+Build a module tool
+"""""""""""""""""""
+
+The first thing that we need is the module tool. In this case we
+choose ``lmod`` as it can work with both hierarchical and non-hierarchical
+module file layouts.
+
+.. code-block:: console
+
+ $ bin/spack install lmod
+
+Once the module tool is installed we need to have it available in the
+current shell. As the installation directories are definitely not easy
+to remember, we'll employ the command ``spack location`` to retrieve the
+``lmod`` prefix directly from Spack:
+
+.. code-block:: console
+
+ $ . $(spack location -i lmod)/lmod/lmod/init/bash
+
+Now we can source the setup file and activate the :ref:`shell support <shell-support>`:
+
+.. code-block:: console
+
+ $ . share/spack/setup_env.sh
+
+.. FIXME: this needs bootstrap support for ``lmod``
+
+.. FIXME: check the docs here, update them if necessary
+ If you need to install Lmod or Environment module you can refer
+ to the documentation :ref:`here <InstallEnvironmentModules>`.
+
+
+""""""""""""""""""
+Add a new compiler
+""""""""""""""""""
+
+The second step is to build a recent compiler. On first use, Spack
+scans the environment and automatically locates the
+compiler(s) already available on the system. This is what you'll see
+on Ubuntu 14.04:
.. code-block:: console
@@ -58,42 +265,78 @@ something like this:
-- gcc ----------------------------------------------------------
gcc@4.8
-In order to showcase the capabilities of module customization, we will want to
-build a limited set of packages with multiple compilers. If you do not already
-have multiple compilers listed by ``spack compilers``, you should build one
-with Spack:
+Let's bootstrap a more recent compiler with the one that was automatically detected:
+
+.. code-block:: console
+
+ $ spack install gcc@7.2.0
+ ...
+ Wait a long time
+ ...
+
+Once ``gcc`` is installed we can use shell support to load it and make
+it readily available:
.. code-block:: console
- $ spack install gcc@6.2.0
- # ...
- # Wait a long time
- # ...
+ $ spack load gcc@7.2.0
+
+It may not be apparent, but the last command employed the module files
+generated automatically by Spack. What happens under the hood when you use
+the ``spack load`` command is:
-Then we can use shell support for modules to add it to the list of known compilers:
+1. the spec passed as argument is translated into a module file name
+2. the current module tool is used to load that module file
+
+You can use this command to double check:
.. code-block:: console
- # The name of the generated module may vary
- $ module load gcc-6.2.0-gcc-4.8-twd5nqg
+ $ module list
+ Currently Loaded Modules:
+ 1) lmod-7.7-gcc-4.8-okcwjgw 2) gcc-7.2.0-gcc-4.8-twd5nqg
+
+Note that the 7-digit hash at the end of the generated module may vary depending
+on architecture or package version. Now that we have ``gcc@7.2.0`` in ``PATH`` we
+can finally add it to the list of compilers known to Spack:
+
+.. code-block:: console
$ spack compiler add
==> Added 1 new compiler to ~/.spack/linux/compilers.yaml
- gcc@6.2.0
+ gcc@7.2.0
$ spack compilers
==> Available compilers
-- gcc ----------------------------------------------------------
- gcc@6.2.0 gcc@4.8
+ gcc@7.2.0 gcc@4.8
-Note that the 7-digit hash at the end of the generated module may vary depending
-on architecture or package version.
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Build software that will be used in the tutorial
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+Build the software that will be used in the tutorial
+""""""""""""""""""""""""""""""""""""""""""""""""""""
-Next you should install a few modules that will be used in the tutorial:
+The last step is to install the software stack needed later on. To mimic
+an external installation of an MPI provider we'll install ``openmpi`` on
+the system we are working on. On Ubuntu 14.04 it boils down to:
+
+.. code-block:: console
+
+ $ sudo apt-get install openmpi-bin openmpi-common libopenmpi-dev
+ ...
+
+but the exact command varies according to your OS. Then we need to prepare
+a ``packages.yaml`` file that instructs Spack to use an externally provided MPI:
+
+.. code-block:: yaml
+
+ packages:
+ openmpi:
+ buildable: False
+ paths:
+ openmpi@1.6: /usr
+
+Finally, we should use Spack to install the packages used in the examples:
.. code-block:: console
@@ -103,56 +346,66 @@ Next you should install a few modules that will be used in the tutorial:
$ spack install netlib-scalapack ^mpich ^netlib-lapack
$ spack install py-scipy ^openblas
-In the end your environment should look something like:
+
+.. _module_file_tutorial_non_hierarchical:
+
+-----------------------------
+Non-hierarchical module files
+-----------------------------
+
+If you arrived to this point you should have an environment that looks similar to:
.. code-block:: console
- $ module avail
+ root@module-file-tutorial:/# module avail
- ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
- binutils-2.27-gcc-4.8-dz3xevw libpciaccess-0.13.4-gcc-6.2.0-eo2siet lzo-2.09-gcc-6.2.0-jcngz72 netlib-scalapack-2.0.2-gcc-6.2.0-wnimqhw python-2.7.12-gcc-6.2.0-qu7rc5p
- bzip2-1.0.6-gcc-6.2.0-csoc2mq libsigsegv-2.10-gcc-4.8-avb6azw m4-1.4.17-gcc-4.8-iggewke netlib-scalapack-2.0.2-gcc-6.2.0-wojunhq sqlite-3.8.5-gcc-6.2.0-td3zfe7
- cmake-3.5.2-gcc-6.2.0-6poypqg libsigsegv-2.10-gcc-6.2.0-g3qpmbi m4-1.4.17-gcc-6.2.0-lhgqa6s nettle-3.2-gcc-6.2.0-djdthlh tcl-8.6.5-gcc-4.8-atddxu7
- curl-7.50.3-gcc-6.2.0-2ffacqm libtool-2.4.6-gcc-6.2.0-kiepac6 mpc-1.0.3-gcc-4.8-lylv7lk openblas-0.2.19-gcc-6.2.0-js33umc util-macros-1.19.0-gcc-6.2.0-uoukuqk
- expat-2.2.0-gcc-6.2.0-bxqnjar libxml2-2.9.4-gcc-6.2.0-3k4ykbe mpfr-3.1.4-gcc-4.8-bldfx3w openmpi-2.0.1-gcc-6.2.0-s3qbtby xz-5.2.2-gcc-6.2.0-t5lk6in
- gcc-6.2.0-gcc-4.8-twd5nqg lmod-6.4.5-gcc-4.8-7v7bh7b mpich-3.2-gcc-6.2.0-5n5xoep openssl-1.0.2j-gcc-6.2.0-hibnfda zlib-1.2.8-gcc-4.8-bds4ies
- gmp-6.1.1-gcc-4.8-uq52e2n lua-5.3.2-gcc-4.8-xozf2hx ncurses-6.0-gcc-4.8-u62fit4 pkg-config-0.29.1-gcc-6.2.0-rslsgcs zlib-1.2.8-gcc-6.2.0-asydrba
- gmp-6.1.1-gcc-6.2.0-3cfh3hi lua-luafilesystem-1_6_3-gcc-4.8-sbzejlz ncurses-6.0-gcc-6.2.0-7tb426s py-nose-1.3.7-gcc-6.2.0-4gl5c42
- hwloc-1.11.4-gcc-6.2.0-3ostwel lua-luaposix-33.4.0-gcc-4.8-xf7y2p5 netlib-lapack-3.6.1-gcc-6.2.0-mirer2l py-numpy-1.11.1-gcc-6.2.0-i3rpk4e
- isl-0.14-gcc-4.8-cq73t5m lz4-131-gcc-6.2.0-cagoem4 netlib-scalapack-2.0.2-gcc-6.2.0-6bqlxqy py-scipy-0.18.1-gcc-6.2.0-e6uljfi
- libarchive-3.2.1-gcc-6.2.0-2b54aos lzma-4.32.7-gcc-6.2.0-sfmeynw netlib-scalapack-2.0.2-gcc-6.2.0-hpqb3dp py-setuptools-25.2.0-gcc-6.2.0-hkqauaa
+ ----------------------------------------------------------------------------- /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64 -----------------------------------------------------------------------------
+ autoconf-2.69-gcc-5.4.0-bvabhji libtool-2.4.6-gcc-5.4.0-o2pfwjf ncurses-6.0-gcc-7.2.0-oh6pqty pkg-config-0.29.2-gcc-5.4.0-ae2hwm7 readline-7.0-gcc-5.4.0-gizxpch
+ automake-1.15.1-gcc-5.4.0-kaiefe4 lmod-7.7-gcc-5.4.0-okcwjgw netlib-lapack-3.6.1-gcc-7.2.0-5sywztc pkg-config-0.29.2-gcc-7.2.0-76z7ehw readline-7.0-gcc-7.2.0-eqos6rz
+ bzip2-1.0.6-gcc-7.2.0-mwamumj lua-5.3.4-gcc-5.4.0-ytxw2gq netlib-scalapack-2.0.2-gcc-7.2.0-5lb2j5p py-appdirs-1.4.3-gcc-7.2.0-7ncu7zr sqlite-3.20.0-gcc-7.2.0-hfmjilk
+ cmake-3.9.4-gcc-7.2.0-6bxdr6h lua-luafilesystem-1_6_3-gcc-5.4.0-5dzzlt4 netlib-scalapack-2.0.2-gcc-7.2.0-ax6aza6 py-numpy-1.13.1-gcc-7.2.0-22n5oub tcl-8.6.6-gcc-5.4.0-767ls4i
+ gcc-7.2.0-gcc-5.4.0-go3z4hb lua-luaposix-33.4.0-gcc-5.4.0-w5jpnwm netlib-scalapack-2.0.2-gcc-7.2.0-c4v5l7j py-packaging-16.8-gcc-7.2.0-c37cjmq zlib-1.2.11-gcc-5.4.0-swly52a
+ gdbm-1.13-gcc-5.4.0-vdhoris m4-1.4.18-gcc-5.4.0-r5envx3 netlib-scalapack-2.0.2-gcc-7.2.0-m7rzcmh py-pyparsing-2.2.0-gcc-7.2.0-ahdh5cx zlib-1.2.11-gcc-7.2.0-lv5fabl
+ git-2.9.4-gcc-5.4.0-atwjs4i mpc-1.0.3-gcc-5.4.0-tumbpsh openblas-0.2.20-gcc-7.2.0-kvddide py-scipy-0.19.1-gcc-7.2.0-7hi7r5j
+ gmp-6.1.2-gcc-5.4.0-qc4qcfz mpfr-3.1.5-gcc-5.4.0-mdi6irz openmpi-1.10.2-gcc-7.2.0-ufw7pdi py-setuptools-35.0.2-gcc-7.2.0-cvasi7i
+ isl-0.18-gcc-5.4.0-vttqout mpich-3.2-gcc-7.2.0-7gxffhv openssl-1.0.2k-gcc-7.2.0-pxv3dh4 py-six-1.10.0-gcc-7.2.0-3xk5mod
+ libsigsegv-2.11-gcc-5.4.0-fypapcp ncurses-6.0-gcc-5.4.0-ukq4tcc perl-5.24.1-gcc-5.4.0-mfzwy6y python-2.7.14-gcc-7.2.0-555u7ea
-------------------------------------------------
-Filter unwanted modifications to the environment
-------------------------------------------------
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
-The non-hierarchical TCL module files that have been generated so far
-follow the default rules for module generation, which are given
-:ref:`here <modules-yaml>` in the reference part of the manual. Taking a
-look at the ``gcc`` module you'll see something like:
+The non-hierarchical module files that have been generated so far
+follow :ref:`the default rules for module generation <modules-yaml>`.
+Taking a look at the ``gcc`` module you'll see, for example:
.. code-block:: console
- $ module show gcc-6.2.0-gcc-4.8-twd5nqg
+ root@module-file-tutorial:/# module show gcc-7.2.0-gcc-5.4.0-go3z4hb
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc-6.2.0-gcc-4.8-twd5nqg:
+ /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64/gcc-7.2.0-gcc-5.4.0-go3z4hb:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- whatis("gcc @6.2.0 ")
- prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
- prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
- prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
- prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
- prepend_path("LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
- prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
- prepend_path("CPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/include")
+ whatis("The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Ada, and Go, as well as libraries for these languages. ")
+ prepend_path("PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/bin")
+ prepend_path("MANPATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/share/man")
+ prepend_path("LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib")
+ prepend_path("LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib64")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib64")
+ prepend_path("CPATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/include")
+ prepend_path("CMAKE_PREFIX_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/")
help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
- Fortran, and Java.
+ Fortran, Ada, and Go, as well as libraries for these languages.
]])
As expected, a few environment variables representing paths will be modified
-by the modules according to the default prefix inspection rules.
+by the module file according to the default prefix inspection rules.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Filter unwanted modifications to the environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Consider now the case that your site has decided that e.g. ``CPATH`` and
+Now consider the case that your site has decided that ``CPATH`` and
``LIBRARY_PATH`` modifications should not be present in module files. What you can
do to abide by the rules is to create a configuration file ``~/.spack/modules.yaml``
with the following content:
@@ -169,14 +422,19 @@ Next you should regenerate all the module files:
.. code-block:: console
- $ spack module refresh --module-type tcl
+ root@module-file-tutorial:/# spack module refresh --module-type tcl
==> You are about to regenerate tcl module files for:
- -- linux-Ubuntu14-x86_64 / gcc@4.8 ------------------------------
- dz3xevw binutils@2.27 uq52e2n gmp@6.1.1 avb6azw libsigsegv@2.10 xozf2hx lua@5.3.2 xf7y2p5 lua-luaposix@33.4.0 lylv7lk mpc@1.0.3 u62fit4 ncurses@6.0 bds4ies zlib@1.2.8
- twd5nqg gcc@6.2.0 cq73t5m isl@0.14 7v7bh7b lmod@6.4.5 sbzejlz lua-luafilesystem@1_6_3 iggewke m4@1.4.17 bldfx3w mpfr@3.1.4 atddxu7 tcl@8.6.5
+ -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+ bvabhji autoconf@2.69 vdhoris gdbm@1.13 vttqout isl@0.18 okcwjgw lmod@7.7 w5jpnwm lua-luaposix@33.4.0 mdi6irz mpfr@3.1.5 ae2hwm7 pkg-config@0.29.2 swly52a zlib@1.2.11
+ kaiefe4 automake@1.15.1 atwjs4i git@2.9.4 fypapcp libsigsegv@2.11 ytxw2gq lua@5.3.4 r5envx3 m4@1.4.18 ukq4tcc ncurses@6.0 gizxpch readline@7.0
+ go3z4hb gcc@7.2.0 qc4qcfz gmp@6.1.2 o2pfwjf libtool@2.4.6 5dzzlt4 lua-luafilesystem@1_6_3 tumbpsh mpc@1.0.3 mfzwy6y perl@5.24.1 767ls4i tcl@8.6.6
- ...
+ -- linux-ubuntu16.04-x86_64 / gcc@7.2.0 -------------------------
+ mwamumj bzip2@1.0.6 5sywztc netlib-lapack@3.6.1 m7rzcmh netlib-scalapack@2.0.2 76z7ehw pkg-config@0.29.2 ahdh5cx py-pyparsing@2.2.0 555u7ea python@2.7.14
+ 6bxdr6h cmake@3.9.4 ax6aza6 netlib-scalapack@2.0.2 kvddide openblas@0.2.20 7ncu7zr py-appdirs@1.4.3 7hi7r5j py-scipy@0.19.1 eqos6rz readline@7.0
+ 7gxffhv mpich@3.2 c4v5l7j netlib-scalapack@2.0.2 ufw7pdi openmpi@1.10.2 22n5oub py-numpy@1.13.1 cvasi7i py-setuptools@35.0.2 hfmjilk sqlite@3.20.0
+ oh6pqty ncurses@6.0 5lb2j5p netlib-scalapack@2.0.2 pxv3dh4 openssl@1.0.2k c37cjmq py-packaging@16.8 3xk5mod py-six@1.10.0 lv5fabl zlib@1.2.11
==> Do you want to proceed? [y/n] y
==> Regenerating tcl module files
@@ -186,30 +444,30 @@ paths have disappeared:
.. code-block:: console
- $ module show gcc-6.2.0-gcc-4.8-twd5nqg
+ root@module-file-tutorial:/# module show gcc-7.2.0-gcc-5.4.0-go3z4hb
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc-6.2.0-gcc-4.8-twd5nqg:
+ /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64/gcc-7.2.0-gcc-5.4.0-go3z4hb:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- whatis("gcc @6.2.0 ")
- prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
- prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
- prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
- prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
- prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
+ whatis("The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Ada, and Go, as well as libraries for these languages. ")
+ prepend_path("PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/bin")
+ prepend_path("MANPATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/share/man")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib64")
+ prepend_path("CMAKE_PREFIX_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/")
help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
- Fortran, and Java.
+ Fortran, Ada, and Go, as well as libraries for these languages.
]])
-----------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Prevent some module files from being generated
-----------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Another common request at many sites is to avoid exposing software that
is only needed as an intermediate step when building a newer stack.
Let's try to prevent the generation of
-module files for anything that is compiled with ``gcc@4.8`` (the OS provided compiler).
+module files for anything that is compiled with ``gcc@5.4.0`` (the OS provided compiler).
-To do this you should add a ``blacklist`` keyword to the configuration file:
+To do this you should add a ``blacklist`` keyword to ``~/.spack/modules.yaml``:
.. code-block:: yaml
:emphasize-lines: 3,4
@@ -217,7 +475,7 @@ To do this you should add a ``blacklist`` keyword to the configuration file:
modules:
tcl:
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
filter:
environment_blacklist: ['CPATH', 'LIBRARY_PATH']
@@ -226,41 +484,41 @@ and regenerate the module files:
.. code-block:: console
- $ spack module refresh --module-type tcl --delete-tree
+ root@module-file-tutorial:/# spack module refresh --module-type tcl --delete-tree
==> You are about to regenerate tcl module files for:
- -- linux-Ubuntu14-x86_64 / gcc@4.8 ------------------------------
- dz3xevw binutils@2.27 uq52e2n gmp@6.1.1 avb6azw libsigsegv@2.10 xozf2hx lua@5.3.2 xf7y2p5 lua-luaposix@33.4.0 lylv7lk mpc@1.0.3 u62fit4 ncurses@6.0 bds4ies zlib@1.2.8
- twd5nqg gcc@6.2.0 cq73t5m isl@0.14 7v7bh7b lmod@6.4.5 sbzejlz lua-luafilesystem@1_6_3 iggewke m4@1.4.17 bldfx3w mpfr@3.1.4 atddxu7 tcl@8.6.5
+ -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+ bvabhji autoconf@2.69 vdhoris gdbm@1.13 vttqout isl@0.18 okcwjgw lmod@7.7 w5jpnwm lua-luaposix@33.4.0 mdi6irz mpfr@3.1.5 ae2hwm7 pkg-config@0.29.2 swly52a zlib@1.2.11
+ kaiefe4 automake@1.15.1 atwjs4i git@2.9.4 fypapcp libsigsegv@2.11 ytxw2gq lua@5.3.4 r5envx3 m4@1.4.18 ukq4tcc ncurses@6.0 gizxpch readline@7.0
+ go3z4hb gcc@7.2.0 qc4qcfz gmp@6.1.2 o2pfwjf libtool@2.4.6 5dzzlt4 lua-luafilesystem@1_6_3 tumbpsh mpc@1.0.3 mfzwy6y perl@5.24.1 767ls4i tcl@8.6.6
- -- linux-Ubuntu14-x86_64 / gcc@6.2.0 ----------------------------
- csoc2mq bzip2@1.0.6 2b54aos libarchive@3.2.1 sfmeynw lzma@4.32.7 wnimqhw netlib-scalapack@2.0.2 s3qbtby openmpi@2.0.1 hkqauaa py-setuptools@25.2.0
- 6poypqg cmake@3.5.2 eo2siet libpciaccess@0.13.4 jcngz72 lzo@2.09 6bqlxqy netlib-scalapack@2.0.2 hibnfda openssl@1.0.2j qu7rc5p python@2.7.12
- 2ffacqm curl@7.50.3 g3qpmbi libsigsegv@2.10 lhgqa6s m4@1.4.17 wojunhq netlib-scalapack@2.0.2 rslsgcs pkg-config@0.29.1 td3zfe7 sqlite@3.8.5
- bxqnjar expat@2.2.0 kiepac6 libtool@2.4.6 5n5xoep mpich@3.2 hpqb3dp netlib-scalapack@2.0.2 4gl5c42 py-nose@1.3.7 uoukuqk util-macros@1.19.0
- 3cfh3hi gmp@6.1.1 3k4ykbe libxml2@2.9.4 7tb426s ncurses@6.0 djdthlh nettle@3.2 i3rpk4e py-numpy@1.11.1 t5lk6in xz@5.2.2
- 3ostwel hwloc@1.11.4 cagoem4 lz4@131 mirer2l netlib-lapack@3.6.1 js33umc openblas@0.2.19 e6uljfi py-scipy@0.18.1 asydrba zlib@1.2.8
+ -- linux-ubuntu16.04-x86_64 / gcc@7.2.0 -------------------------
+ mwamumj bzip2@1.0.6 5sywztc netlib-lapack@3.6.1 m7rzcmh netlib-scalapack@2.0.2 76z7ehw pkg-config@0.29.2 ahdh5cx py-pyparsing@2.2.0 555u7ea python@2.7.14
+ 6bxdr6h cmake@3.9.4 ax6aza6 netlib-scalapack@2.0.2 kvddide openblas@0.2.20 7ncu7zr py-appdirs@1.4.3 7hi7r5j py-scipy@0.19.1 eqos6rz readline@7.0
+ 7gxffhv mpich@3.2 c4v5l7j netlib-scalapack@2.0.2 ufw7pdi openmpi@1.10.2 22n5oub py-numpy@1.13.1 cvasi7i py-setuptools@35.0.2 hfmjilk sqlite@3.20.0
+ oh6pqty ncurses@6.0 5lb2j5p netlib-scalapack@2.0.2 pxv3dh4 openssl@1.0.2k c37cjmq py-packaging@16.8 3xk5mod py-six@1.10.0 lv5fabl zlib@1.2.11
==> Do you want to proceed? [y/n] y
+ ==> Regenerating tcl module files
+
+ root@module-file-tutorial:/# module avail
- $ module avail
+ ----------------------------------------------------------------------------- /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64 -----------------------------------------------------------------------------
+ bzip2-1.0.6-gcc-7.2.0-mwamumj netlib-scalapack-2.0.2-gcc-7.2.0-5lb2j5p openmpi-1.10.2-gcc-7.2.0-ufw7pdi py-packaging-16.8-gcc-7.2.0-c37cjmq python-2.7.14-gcc-7.2.0-555u7ea
+ cmake-3.9.4-gcc-7.2.0-6bxdr6h netlib-scalapack-2.0.2-gcc-7.2.0-ax6aza6 openssl-1.0.2k-gcc-7.2.0-pxv3dh4 py-pyparsing-2.2.0-gcc-7.2.0-ahdh5cx readline-7.0-gcc-7.2.0-eqos6rz
+ mpich-3.2-gcc-7.2.0-7gxffhv netlib-scalapack-2.0.2-gcc-7.2.0-c4v5l7j pkg-config-0.29.2-gcc-7.2.0-76z7ehw py-scipy-0.19.1-gcc-7.2.0-7hi7r5j sqlite-3.20.0-gcc-7.2.0-hfmjilk
+ ncurses-6.0-gcc-7.2.0-oh6pqty netlib-scalapack-2.0.2-gcc-7.2.0-m7rzcmh py-appdirs-1.4.3-gcc-7.2.0-7ncu7zr py-setuptools-35.0.2-gcc-7.2.0-cvasi7i zlib-1.2.11-gcc-7.2.0-lv5fabl
+ netlib-lapack-3.6.1-gcc-7.2.0-5sywztc openblas-0.2.20-gcc-7.2.0-kvddide py-numpy-1.13.1-gcc-7.2.0-22n5oub py-six-1.10.0-gcc-7.2.0-3xk5mod
- ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
- bzip2-1.0.6-gcc-6.2.0-csoc2mq libsigsegv-2.10-gcc-6.2.0-g3qpmbi ncurses-6.0-gcc-6.2.0-7tb426s openmpi-2.0.1-gcc-6.2.0-s3qbtby sqlite-3.8.5-gcc-6.2.0-td3zfe7
- cmake-3.5.2-gcc-6.2.0-6poypqg libtool-2.4.6-gcc-6.2.0-kiepac6 netlib-lapack-3.6.1-gcc-6.2.0-mirer2l openssl-1.0.2j-gcc-6.2.0-hibnfda util-macros-1.19.0-gcc-6.2.0-uoukuqk
- curl-7.50.3-gcc-6.2.0-2ffacqm libxml2-2.9.4-gcc-6.2.0-3k4ykbe netlib-scalapack-2.0.2-gcc-6.2.0-6bqlxqy pkg-config-0.29.1-gcc-6.2.0-rslsgcs xz-5.2.2-gcc-6.2.0-t5lk6in
- expat-2.2.0-gcc-6.2.0-bxqnjar lz4-131-gcc-6.2.0-cagoem4 netlib-scalapack-2.0.2-gcc-6.2.0-hpqb3dp py-nose-1.3.7-gcc-6.2.0-4gl5c42 zlib-1.2.8-gcc-6.2.0-asydrba
- gmp-6.1.1-gcc-6.2.0-3cfh3hi lzma-4.32.7-gcc-6.2.0-sfmeynw netlib-scalapack-2.0.2-gcc-6.2.0-wnimqhw py-numpy-1.11.1-gcc-6.2.0-i3rpk4e
- hwloc-1.11.4-gcc-6.2.0-3ostwel lzo-2.09-gcc-6.2.0-jcngz72 netlib-scalapack-2.0.2-gcc-6.2.0-wojunhq py-scipy-0.18.1-gcc-6.2.0-e6uljfi
- libarchive-3.2.1-gcc-6.2.0-2b54aos m4-1.4.17-gcc-6.2.0-lhgqa6s nettle-3.2-gcc-6.2.0-djdthlh py-setuptools-25.2.0-gcc-6.2.0-hkqauaa
- libpciaccess-0.13.4-gcc-6.2.0-eo2siet mpich-3.2-gcc-6.2.0-5n5xoep openblas-0.2.19-gcc-6.2.0-js33umc python-2.7.12-gcc-6.2.0-qu7rc5p
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
This time it is convenient to pass the option ``--delete-tree`` to the command that
regenerates the module files to instruct it to delete the existing tree and regenerate
a new one instead of overwriting the files in the existing directory.
-If you pay careful attention you'll see though that we went too far in blacklisting modules:
-the module for ``gcc@6.2.0`` disappeared as it was bootstrapped with ``gcc@4.8``. To specify
+If you look closely you'll see though that we went too far in blacklisting modules:
+the module for ``gcc@7.2.0`` disappeared as it was bootstrapped with ``gcc@5.4.0``. To specify
exceptions to the blacklist rules you can use ``whitelist``:
.. code-block:: yaml
@@ -271,7 +529,7 @@ exceptions to the blacklist rules you can use ``whitelist``:
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
filter:
environment_blacklist: ['CPATH', 'LIBRARY_PATH']
@@ -280,20 +538,26 @@ exceptions to the blacklist rules you can use ``whitelist``:
.. code-block:: console
- $ spack module refresh --module-type tcl -y
+ root@module-file-tutorial:/# spack module refresh --module-type tcl -y
+ ==> Regenerating tcl module files
+
-you'll see that now the module for ``gcc@6.2.0`` has reappeared:
+you'll see that now the module for ``gcc@7.2.0`` has reappeared:
.. code-block:: console
- $ module avail gcc-6.2.0-gcc-4.8-twd5nqg
+ root@module-file-tutorial:/# module avail gcc-7.2.0-gcc-5.4.0-go3z4hb
- ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
- gcc-6.2.0-gcc-4.8-twd5nqg
+ ----------------------------------------------------------------------------- /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64 -----------------------------------------------------------------------------
+ gcc-7.2.0-gcc-5.4.0-go3z4hb
--------------------------
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
Change module file naming
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
The next step in making module files more user-friendly is to
improve their naming scheme.
@@ -311,7 +575,7 @@ use the ``hash_length`` keyword in the configuration file:
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
filter:
environment_blacklist: ['CPATH', 'LIBRARY_PATH']
@@ -320,14 +584,14 @@ If you try to regenerate the module files now you will get an error:
.. code-block:: console
- $ spack module refresh --module-type tcl --delete-tree -y
+ root@module-file-tutorial:/# spack module refresh --module-type tcl --delete-tree -y
==> Error: Name clashes detected in module files:
- file : ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/netlib-scalapack-2.0.2-gcc-6.2.0
- spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
- spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
- spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
- spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
+ file: /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64/netlib-scalapack-2.0.2-gcc-7.2.0
+ spec: netlib-scalapack@2.0.2%gcc@7.2.0 build_type=RelWithDebInfo ~pic+shared arch=linux-ubuntu16.04-x86_64
+ spec: netlib-scalapack@2.0.2%gcc@7.2.0 build_type=RelWithDebInfo ~pic+shared arch=linux-ubuntu16.04-x86_64
+ spec: netlib-scalapack@2.0.2%gcc@7.2.0 build_type=RelWithDebInfo ~pic+shared arch=linux-ubuntu16.04-x86_64
+ spec: netlib-scalapack@2.0.2%gcc@7.2.0 build_type=RelWithDebInfo ~pic+shared arch=linux-ubuntu16.04-x86_64
==> Error: Operation aborted
@@ -338,7 +602,7 @@ If you try to regenerate the module files now you will get an error:
The problem here is that without
the hashes the four different flavors of ``netlib-scalapack`` map to the same module file
-name. We have the possibility to add suffixes to differentiate them:
+name. We can add suffixes to differentiate them:
.. code-block:: yaml
:emphasize-lines: 9-11,14-17
@@ -349,7 +613,7 @@ name. We have the possibility to add suffixes to differentiate them:
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
suffixes:
'^openblas': openblas
@@ -361,25 +625,26 @@ name. We have the possibility to add suffixes to differentiate them:
'^openmpi': openmpi
'^mpich': mpich
-As you can see it is possible to specify rules that applies only to a
+As you can see it is possible to specify rules that apply only to a
restricted set of packages using :ref:`anonymous specs <anonymous_specs>`.
Regenerating module files now we obtain:
.. code-block:: console
- $ spack module refresh --module-type tcl --delete-tree -y
+ root@module-file-tutorial:/# spack module refresh --module-type tcl --delete-tree -y
==> Regenerating tcl module files
- $ module avail
-
- ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
- bzip2-1.0.6-gcc-6.2.0 libpciaccess-0.13.4-gcc-6.2.0 mpich-3.2-gcc-6.2.0 openblas-0.2.19-gcc-6.2.0 python-2.7.12-gcc-6.2.0
- cmake-3.5.2-gcc-6.2.0 libsigsegv-2.10-gcc-6.2.0 ncurses-6.0-gcc-6.2.0 openmpi-2.0.1-gcc-6.2.0 sqlite-3.8.5-gcc-6.2.0
- curl-7.50.3-gcc-6.2.0 libtool-2.4.6-gcc-6.2.0 netlib-lapack-3.6.1-gcc-6.2.0 openssl-1.0.2j-gcc-6.2.0 util-macros-1.19.0-gcc-6.2.0
- expat-2.2.0-gcc-6.2.0 libxml2-2.9.4-gcc-6.2.0 netlib-scalapack-2.0.2-gcc-6.2.0-netlib-mpich pkg-config-0.29.1-gcc-6.2.0 xz-5.2.2-gcc-6.2.0
- gcc-6.2.0-gcc-4.8 lz4-131-gcc-6.2.0 netlib-scalapack-2.0.2-gcc-6.2.0-netlib-openmpi py-nose-1.3.7-gcc-6.2.0 zlib-1.2.8-gcc-6.2.0
- gmp-6.1.1-gcc-6.2.0 lzma-4.32.7-gcc-6.2.0 netlib-scalapack-2.0.2-gcc-6.2.0-openblas-mpich py-numpy-1.11.1-gcc-6.2.0-openblas
- hwloc-1.11.4-gcc-6.2.0 lzo-2.09-gcc-6.2.0 netlib-scalapack-2.0.2-gcc-6.2.0-openblas-openmpi py-scipy-0.18.1-gcc-6.2.0-openblas
- libarchive-3.2.1-gcc-6.2.0 m4-1.4.17-gcc-6.2.0 nettle-3.2-gcc-6.2.0 py-setuptools-25.2.0-gcc-6.2.0
+
+ root@module-file-tutorial:/# module avail
+
+ ----------------------------------------------------------------------------- /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64 -----------------------------------------------------------------------------
+ bzip2-1.0.6-gcc-7.2.0 netlib-lapack-3.6.1-gcc-7.2.0 openblas-0.2.20-gcc-7.2.0 py-numpy-1.13.1-gcc-7.2.0-openblas py-six-1.10.0-gcc-7.2.0
+ cmake-3.9.4-gcc-7.2.0 netlib-scalapack-2.0.2-gcc-7.2.0-netlib-mpich openmpi-1.10.2-gcc-7.2.0 py-packaging-16.8-gcc-7.2.0 python-2.7.14-gcc-7.2.0
+ gcc-7.2.0-gcc-5.4.0 netlib-scalapack-2.0.2-gcc-7.2.0-netlib-openmpi openssl-1.0.2k-gcc-7.2.0 py-pyparsing-2.2.0-gcc-7.2.0 readline-7.0-gcc-7.2.0
+ mpich-3.2-gcc-7.2.0 netlib-scalapack-2.0.2-gcc-7.2.0-openblas-mpich pkg-config-0.29.2-gcc-7.2.0 py-scipy-0.19.1-gcc-7.2.0-openblas sqlite-3.20.0-gcc-7.2.0
+ ncurses-6.0-gcc-7.2.0 netlib-scalapack-2.0.2-gcc-7.2.0-openblas-openmpi py-appdirs-1.4.3-gcc-7.2.0 py-setuptools-35.0.2-gcc-7.2.0 zlib-1.2.11-gcc-7.2.0
+
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
Finally we can set a ``naming_scheme`` to prevent users from loading
modules that refer to different flavors of the same library/application:
@@ -394,7 +659,7 @@ modules that refer to different flavors of the same library/application:
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
conflict:
- '${PACKAGE}'
@@ -412,26 +677,31 @@ The final result should look like:
.. code-block:: console
- $ module avail
+ root@module-file-tutorial:/# spack module refresh --module-type tcl --delete-tree -y
+ ==> Regenerating tcl module files
+ root@module-file-tutorial:/# module avail
+
+ ----------------------------------------------------------------------------- /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64 -----------------------------------------------------------------------------
+ bzip2/1.0.6-gcc-7.2.0 netlib-lapack/3.6.1-gcc-7.2.0 openblas/0.2.20-gcc-7.2.0 py-numpy/1.13.1-gcc-7.2.0-openblas py-six/1.10.0-gcc-7.2.0
+ cmake/3.9.4-gcc-7.2.0 netlib-scalapack/2.0.2-gcc-7.2.0-netlib-mpich openmpi/1.10.2-gcc-7.2.0 py-packaging/16.8-gcc-7.2.0 python/2.7.14-gcc-7.2.0
+ gcc/7.2.0-gcc-5.4.0 netlib-scalapack/2.0.2-gcc-7.2.0-netlib-openmpi openssl/1.0.2k-gcc-7.2.0 py-pyparsing/2.2.0-gcc-7.2.0 readline/7.0-gcc-7.2.0
+ mpich/3.2-gcc-7.2.0 netlib-scalapack/2.0.2-gcc-7.2.0-openblas-mpich pkg-config/0.29.2-gcc-7.2.0 py-scipy/0.19.1-gcc-7.2.0-openblas sqlite/3.20.0-gcc-7.2.0
+ ncurses/6.0-gcc-7.2.0 netlib-scalapack/2.0.2-gcc-7.2.0-openblas-openmpi (D) py-appdirs/1.4.3-gcc-7.2.0 py-setuptools/35.0.2-gcc-7.2.0 zlib/1.2.11-gcc-7.2.0
- ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
- bzip2/1.0.6-gcc-6.2.0 libpciaccess/0.13.4-gcc-6.2.0 mpich/3.2-gcc-6.2.0 openblas/0.2.19-gcc-6.2.0 python/2.7.12-gcc-6.2.0
- cmake/3.5.2-gcc-6.2.0 libsigsegv/2.10-gcc-6.2.0 ncurses/6.0-gcc-6.2.0 openmpi/2.0.1-gcc-6.2.0 sqlite/3.8.5-gcc-6.2.0
- curl/7.50.3-gcc-6.2.0 libtool/2.4.6-gcc-6.2.0 netlib-lapack/3.6.1-gcc-6.2.0 openssl/1.0.2j-gcc-6.2.0 util-macros/1.19.0-gcc-6.2.0
- expat/2.2.0-gcc-6.2.0 libxml2/2.9.4-gcc-6.2.0 netlib-scalapack/2.0.2-gcc-6.2.0-netlib-mpich pkg-config/0.29.1-gcc-6.2.0 xz/5.2.2-gcc-6.2.0
- gcc/6.2.0-gcc-4.8 lz4/131-gcc-6.2.0 netlib-scalapack/2.0.2-gcc-6.2.0-netlib-openmpi py-nose/1.3.7-gcc-6.2.0 zlib/1.2.8-gcc-6.2.0
- gmp/6.1.1-gcc-6.2.0 lzma/4.32.7-gcc-6.2.0 netlib-scalapack/2.0.2-gcc-6.2.0-openblas-mpich py-numpy/1.11.1-gcc-6.2.0-openblas
- hwloc/1.11.4-gcc-6.2.0 lzo/2.09-gcc-6.2.0 netlib-scalapack/2.0.2-gcc-6.2.0-openblas-openmpi (D) py-scipy/0.18.1-gcc-6.2.0-openblas
- libarchive/3.2.1-gcc-6.2.0 m4/1.4.17-gcc-6.2.0 nettle/3.2-gcc-6.2.0 py-setuptools/25.2.0-gcc-6.2.0
+ Where:
+ D: Default Module
+
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
.. note::
TCL specific directive
- The directives ``naming_scheme`` and ``conflict`` are TCL specific and do not apply
- to the ``dotkit`` or ``lmod`` sections in the configuration file.
+ The directives ``naming_scheme`` and ``conflict`` are TCL specific and
+ can't be used in the ``lmod`` section of the configuration file.
-------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Add custom environment modifications
-------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
At many sites it is customary to set an environment variable in a
package's module file that points to the folder in which the package
@@ -448,7 +718,7 @@ is installed. You can achieve this with Spack by adding an
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
conflict:
- '${PACKAGE}'
@@ -465,33 +735,36 @@ is installed. You can achieve this with Spack by adding an
'^openmpi': openmpi
'^mpich': mpich
-There are many variable tokens available to use in the ``environment``
-and ``naming_scheme`` directives, such as ``${PACKAGE}``,
-``${VERSION}``, etc. (see the :meth:`~spack.spec.Spec.format` API
-documentation for the complete list).
+Under the hood Spack uses the :meth:`~spack.spec.Spec.format` API to substitute
+tokens in either environment variable names or values. There are two caveats though:
+
+- The set of allowed tokens in variable names is restricted to ``PACKAGE``,
+ ``VERSION``, ``COMPILER``, ``COMPILERNAME``, ``COMPILERVER``, ``ARCHITECTURE``
+- Any token expanded in a variable name is made uppercase, but other than that
+ case sensitivity is preserved
-Regenerating the module files should result in something like:
+Regenerating the module files results in something like:
.. code-block:: console
- :emphasize-lines: 14
+ :emphasize-lines: 15
- $ spack module refresh -y --module-type tcl
+ root@module-file-tutorial:/# spack module refresh -y --module-type tcl
==> Regenerating tcl module files
- $ module show gcc
+ root@module-file-tutorial:/# module show gcc
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc/6.2.0-gcc-4.8:
+ /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64/gcc/7.2.0-gcc-5.4.0:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- whatis("gcc @6.2.0 ")
- prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
- prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
- prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
- prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
- prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
- setenv("GCC_ROOT","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u")
+ whatis("The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Ada, and Go, as well as libraries for these languages. ")
conflict("gcc")
+ prepend_path("PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/bin")
+ prepend_path("MANPATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/share/man")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib64")
+ prepend_path("CMAKE_PREFIX_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/")
+ setenv("GCC_ROOT","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd")
help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
- Fortran, and Java.
+ Fortran, Ada, and Go, as well as libraries for these languages.
]])
As you can see, the ``gcc`` module has the environment variable ``GCC_ROOT`` set.
@@ -511,7 +784,7 @@ etc. in the ``gcc`` module file and apply other custom modifications to the
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
conflict:
- '${PACKAGE}'
@@ -546,47 +819,47 @@ This time we will be more selective and regenerate only the ``gcc`` and
.. code-block:: console
- $ spack module refresh -y --module-type tcl gcc
+ root@module-file-tutorial:/# spack module refresh -y --module-type tcl gcc
==> Regenerating tcl module files
- $ spack module refresh -y --module-type tcl openmpi
+ root@module-file-tutorial:/# spack module refresh -y --module-type tcl openmpi
==> Regenerating tcl module files
- $ module show gcc
+ root@module-file-tutorial:/# module show gcc
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc/6.2.0-gcc-4.8:
+ /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64/gcc/7.2.0-gcc-5.4.0:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- whatis("gcc @6.2.0 ")
- prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
- prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
- prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
- prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
- prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
- setenv("GCC_ROOT","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u")
+ whatis("The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Ada, and Go, as well as libraries for these languages. ")
+ conflict("gcc")
+ prepend_path("PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/bin")
+ prepend_path("MANPATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/share/man")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib")
+ prepend_path("LD_LIBRARY_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/lib64")
+ prepend_path("CMAKE_PREFIX_PATH","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd/")
+ setenv("GCC_ROOT","/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gcc-7.2.0-go3z4hbsa6wycoaedr3fforx5qnazdhd")
setenv("CC","gcc")
setenv("CXX","g++")
- setenv("F90","gfortran")
setenv("FC","gfortran")
+ setenv("F90","gfortran")
setenv("F77","gfortran")
- conflict("gcc")
help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
- Fortran, and Java.
+ Fortran, Ada, and Go, as well as libraries for these languages.
]])
- $ module show openmpi
+ root@module-file-tutorial:/# module show openmpi
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/openmpi/2.0.1-gcc-6.2.0:
+ /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64/openmpi/1.10.2-gcc-7.2.0:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- whatis("openmpi @2.0.1 ")
- prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/bin")
- prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/")
- prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/lib")
- prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/lib/pkgconfig")
- prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/share/man")
- setenv("SLURM_MPI_TYPE","pmi2")
- setenv("OMPI_MCA_BTL_OPENIB_WARN_DEFAULT_GID_PREFIX","0")
- setenv("OPENMPI_ROOT","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w")
+ whatis("The Open MPI Project is an open source Message Passing Interface implementation that is developed and maintained by a consortium of academic, research, and industry partners. Open MPI is therefore able t
+ o combine the expertise, technologies, and resources from all across the High Performance Computing community in order to build the best MPI library available. Open MPI offers advantages for system and software
+ vendors, application developers and computer science researchers. ")
conflict("openmpi")
+ prepend_path("MANPATH","/usr/share/man")
+ prepend_path("ACLOCAL_PATH","/usr/share/aclocal")
+ prepend_path("PKG_CONFIG_PATH","/usr/lib/pkgconfig")
+ setenv("OPENMPI_ROOT","/usr")
+ setenv("SLURM_MPI_TYPE","pmi2")
+ setenv("OMPI_MCA_btl_openib_warn_default_gid_prefix","0")
help([[The Open MPI Project is an open source Message Passing Interface
implementation that is developed and maintained by a consortium of
academic, research, and industry partners. Open MPI is therefore able to
@@ -597,9 +870,9 @@ This time we will be more selective and regenerate only the ``gcc`` and
]])
----------------------
+^^^^^^^^^^^^^^^^^^^^^
Autoload dependencies
----------------------
+^^^^^^^^^^^^^^^^^^^^^
Spack can also generate module files that contain code to load the
dependencies automatically. You can, for instance generate python
@@ -617,7 +890,7 @@ directive and assigning it the value ``direct``:
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
conflict:
- '${PACKAGE}'
@@ -653,7 +926,7 @@ and regenerating the module files for every package that depends on ``python``:
.. code-block:: console
- $ spack module refresh -y --module-type tcl ^python
+ root@module-file-tutorial:/# spack module refresh -y --module-type tcl ^python
==> Regenerating tcl module files
Now the ``py-scipy`` module will be:
@@ -661,80 +934,116 @@ Now the ``py-scipy`` module will be:
.. code-block:: tcl
#%Module1.0
- ## Module file created by spack (https://github.com/spack/spack) on 2016-11-02 20:53:21.283547
+ ## Module file created by spack (https://github.com/spack/spack) on 2017-10-07 15:02:14.974937
##
- ## py-scipy@0.18.1%gcc@6.2.0 arch=linux-Ubuntu14-x86_64-e6uljfi
+ ## py-scipy@0.19.1%gcc@7.2.0 arch=linux-ubuntu16.04-x86_64 /7hi7r5j
##
- module-whatis "py-scipy @0.18.1"
+
+
+ module-whatis "SciPy (pronounced 'Sigh Pie') is a Scientific Library for Python. It provides many user-friendly and efficient numerical routines such as routines for numerical integration and optimization."
proc ModulesHelp { } {
- puts stderr "SciPy (pronounced "Sigh Pie") is a Scientific Library for Python. It"
+ puts stderr "SciPy (pronounced 'Sigh Pie') is a Scientific Library for Python. It"
puts stderr "provides many user-friendly and efficient numerical routines such as"
puts stderr "routines for numerical integration and optimization."
}
- if ![ is-loaded python/2.7.12-gcc-6.2.0 ] {
- puts stderr "Autoloading python/2.7.12-gcc-6.2.0"
- module load python/2.7.12-gcc-6.2.0
+ if ![ is-loaded python/2.7.14-gcc-7.2.0 ] {
+ puts stderr "Autoloading python/2.7.14-gcc-7.2.0"
+ module load python/2.7.14-gcc-7.2.0
}
-
- if ![ is-loaded openblas/0.2.19-gcc-6.2.0 ] {
- puts stderr "Autoloading openblas/0.2.19-gcc-6.2.0"
- module load openblas/0.2.19-gcc-6.2.0
+ if ![ is-loaded openblas/0.2.20-gcc-7.2.0 ] {
+ puts stderr "Autoloading openblas/0.2.20-gcc-7.2.0"
+ module load openblas/0.2.20-gcc-7.2.0
}
-
- if ![ is-loaded py-numpy/1.11.1-gcc-6.2.0-openblas ] {
- puts stderr "Autoloading py-numpy/1.11.1-gcc-6.2.0-openblas"
- module load py-numpy/1.11.1-gcc-6.2.0-openblas
+ if ![ is-loaded py-numpy/1.13.1-gcc-7.2.0-openblas ] {
+ puts stderr "Autoloading py-numpy/1.13.1-gcc-7.2.0-openblas"
+ module load py-numpy/1.13.1-gcc-7.2.0-openblas
}
-
- prepend-path CMAKE_PREFIX_PATH "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh/"
- prepend-path LD_LIBRARY_PATH "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh/lib"
- prepend-path PYTHONPATH "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh/lib/python2.7/site-packages"
- setenv PY_SCIPY_ROOT "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh"
conflict py-scipy
+ prepend-path LD_LIBRARY_PATH "/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-7.2.0/py-scipy-0.19.1-7hi7r5jri7bmohh4oontvfxo7rgj4hef/lib"
+ prepend-path CMAKE_PREFIX_PATH "/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-7.2.0/py-scipy-0.19.1-7hi7r5jri7bmohh4oontvfxo7rgj4hef/"
+ prepend-path PYTHONPATH "/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-7.2.0/py-scipy-0.19.1-7hi7r5jri7bmohh4oontvfxo7rgj4hef/lib/python2.7/site-packages"
+ setenv PY_SCIPY_ROOT "/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-7.2.0/py-scipy-0.19.1-7hi7r5jri7bmohh4oontvfxo7rgj4hef"
+
and will contain code to autoload all the dependencies:
.. code-block:: console
- $ module load py-scipy
- Autoloading python/2.7.12-gcc-6.2.0
- Autoloading openblas/0.2.19-gcc-6.2.0
- Autoloading py-numpy/1.11.1-gcc-6.2.0-openblas
+ root@module-file-tutorial:/# module load py-scipy
+ Autoloading python/2.7.14-gcc-7.2.0
+ Autoloading openblas/0.2.20-gcc-7.2.0
+ Autoloading py-numpy/1.13.1-gcc-7.2.0-openblas
In case messages are unwanted during the autoload procedure, it will be
sufficient to omit the line setting ``verbose: True`` in the configuration file above.
------------------------------
-Lua hierarchical module files
------------------------------
+-------------------------
+Hierarchical module files
+-------------------------
+
+So far we worked with non-hierarchical module files, i.e. with module files
+that are all generated in the same root directory and don't attempt to
+dynamically modify the ``MODULEPATH``. This results in a flat module structure where
+all the software is visible at the same time:
+
+.. code-block:: console
+
+ root@module-file-tutorial:/# module avail
+
+ ----------------------------------------------------------------------------- /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64 -----------------------------------------------------------------------------
+ bzip2/1.0.6-gcc-7.2.0 netlib-lapack/3.6.1-gcc-7.2.0 openblas/0.2.20-gcc-7.2.0 py-numpy/1.13.1-gcc-7.2.0-openblas py-six/1.10.0-gcc-7.2.0
+ cmake/3.9.4-gcc-7.2.0 netlib-scalapack/2.0.2-gcc-7.2.0-netlib-mpich openmpi/1.10.2-gcc-7.2.0 py-packaging/16.8-gcc-7.2.0 python/2.7.14-gcc-7.2.0
+ gcc/7.2.0-gcc-5.4.0 netlib-scalapack/2.0.2-gcc-7.2.0-netlib-openmpi openssl/1.0.2k-gcc-7.2.0 py-pyparsing/2.2.0-gcc-7.2.0 readline/7.0-gcc-7.2.0
+ mpich/3.2-gcc-7.2.0 netlib-scalapack/2.0.2-gcc-7.2.0-openblas-mpich pkg-config/0.29.2-gcc-7.2.0 py-scipy/0.19.1-gcc-7.2.0-openblas sqlite/3.20.0-gcc-7.2.0
+ ncurses/6.0-gcc-7.2.0 netlib-scalapack/2.0.2-gcc-7.2.0-openblas-openmpi (D) py-appdirs/1.4.3-gcc-7.2.0 py-setuptools/35.0.2-gcc-7.2.0 zlib/1.2.11-gcc-7.2.0
+
+ Where:
+ D: Default Module
+
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
-In the final part of this tutorial you will modify ``modules.yaml`` to generate
-Lua hierarchical module files. You will see that most of the directives used before
-are also valid in the ``lmod`` context.
+This layout is quite simple to deploy, but you can see from the above snippet
+that nothing prevents users from loading incompatible sets of modules:
+
+.. code-block:: console
+
+ root@module-file-tutorial:/# module load netlib-lapack/3.6.1-gcc-7.2.0 openblas/0.2.20-gcc-7.2.0
+ root@module-file-tutorial:/# module list
+
+ Currently Loaded Modules:
+ 1) netlib-lapack/3.6.1-gcc-7.2.0 2) openblas/0.2.20-gcc-7.2.0
+
+Even if ``conflicts`` directives are carefully placed in module files, they:
+
+ - won't enforce a consistent environment, but will just report an error
+ - need constant updates, for instance as soon as a new compiler or MPI library is installed
+
+`Hierarchical module files <http://lmod.readthedocs.io/en/latest/080_hierarchy.html>`_ try to
+overcome these shortcomings by showing at start-up only a restricted view of what is
+available on the system: more specifically only the software that has been installed with
+OS provided compilers. Among this software there will be other - usually more recent - compilers
+that, once loaded, will prepend new directories to ``MODULEPATH`` unlocking all the software
+that was compiled with them. This "unlocking" idea can then be extended arbitrarily to
+virtual dependencies, as we'll see in the following section.
^^^^^^^^^^^^^^^^^
Core/Compiler/MPI
^^^^^^^^^^^^^^^^^
-.. warning::
- Only LMod supports Lua hierarchical module files
- For this part of the tutorial you need to be using LMod to
- manage your environment.
+The most widely used hierarchy is the so called ``Core/Compiler/MPI`` where, on top
+of the compilers, different MPI libraries also unlock software linked to them.
+There are just a few steps needed to adapt the ``modules.yaml`` file we used previously:
-The most common hierarchy is the so called ``Core/Compiler/MPI``. To have an idea
-how a hierarchy is organized you may refer to the
-`Lmod guide <http://lmod.readthedocs.io/en/latest/080_hierarchy.html>`_.
-Since ``lmod`` is not enabled by default, you need to add it to the list of
-enabled module file generators. The other things you need to do are:
+ #. enable the ``lmod`` file generator
+ #. change the ``tcl`` tag to ``lmod``
+ #. remove ``tcl`` specific directives (``naming_scheme`` and ``conflict``)
+ #. declare which compilers are considered ``core_compilers``
+ #. remove the ``mpi`` related suffixes (as they will be substituted by hierarchies)
-- change the ``tcl`` tag to ``lmod``
-- remove ``tcl`` specific directives (``naming_scheme`` and ``conflict``)
-- set which compilers are considered ``core``
-- remove the ``mpi`` related suffixes (as they will be substituted by hierarchies)
-
-After modifications the configuration file will be:
+After these modifications your configuration file should look like:
.. code-block:: yaml
:emphasize-lines: 2-8
@@ -744,14 +1053,14 @@ After modifications the configuration file will be:
- lmod
lmod:
core_compilers:
- - 'gcc@4.8'
+ - 'gcc@5.4.0'
hierarchy:
- mpi
hash_length: 0
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
all:
suffixes:
'^openblas': openblas
@@ -777,112 +1086,168 @@ After modifications the configuration file will be:
.. note::
- The double colon
+ Double colon in configuration files
The double colon after ``enable`` is intentional and it serves the
purpose of overriding the default list of enabled generators so
- that only ``lmod`` will be active (see :ref:`the reference
- manual <config-overrides>` for a more detailed explanation of
- config scopes). If a single colon is used, it will append instead
- of override.
+ that only ``lmod`` will be active (see :ref:`config-overrides` for more
+ details).
-The directive ``core_compilers`` accepts a list of compilers; everything built
-using these compilers will create a module in the ``Core`` part of the hierarchy. It is
+The directive ``core_compilers`` accepts a list of compilers. Everything built
+using these compilers will create a module in the ``Core`` part of the hierarchy,
+which is the entry point for hierarchical module files. It is
common practice to put the OS provided compilers in the list and only build common utilities
-and other compilers in ``Core``.
+and other compilers with them.
-If you regenerate the module files
+If we now regenerate the module files:
.. code-block:: console
- $ spack module refresh --module-type lmod --delete-tree -y
+ root@module-file-tutorial:/# spack module refresh --module-type lmod --delete-tree -y
+ ==> Regenerating lmod module files
-and update ``MODULEPATH`` to point to the ``Core`` folder, and
-list the available modules, you'll see:
+and update ``MODULEPATH`` to point to the ``Core``:
.. code-block:: console
- $ module unuse ~/spack/share/spack/modules/linux-Ubuntu14-x86_64
- $ module use ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core
- $ module avail
+ root@module-file-tutorial:/# module unuse /usr/local/share/spack/modules/linux-ubuntu16.04-x86_64
+ root@module-file-tutorial:/# module use /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/Core
+
+asking for the available modules will return:
+
+.. code-block:: console
+
+ root@module-file-tutorial:/# module avail
+
+ ---------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/Core ----------------------------------------------------------------------------
+ gcc/7.2.0
- ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
- gcc/6.2.0
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
-The only module visible now is ``gcc``. Loading that you will make
-visible the ``Compiler`` part of the software stack that was built with ``gcc/6.2.0``:
+Unsurprisingly, the only visible module is ``gcc``. Loading that we'll unlock
+the ``Compiler`` part of the hierarchy:
.. code-block:: console
- $ module load gcc
- $ module avail
+ root@module-file-tutorial:/# module load gcc
+ root@module-file-tutorial:/# module avail
- -------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/gcc/6.2.0 ---------------------------------------------------------------------
- binutils/2.27 curl/7.50.3 hwloc/1.11.4 libtool/2.4.6 lzo/2.09 netlib-lapack/3.6.1 openssl/1.0.2j py-scipy/0.18.1-openblas util-macros/1.19.0
- bison/3.0.4 expat/2.2.0 libarchive/3.2.1 libxml2/2.9.4 m4/1.4.17 nettle/3.2 pkg-config/0.29.1 py-setuptools/25.2.0 xz/5.2.2
- bzip2/1.0.6 flex/2.6.0 libpciaccess/0.13.4 lz4/131 mpich/3.2 openblas/0.2.19 py-nose/1.3.7 python/2.7.12 zlib/1.2.8
- cmake/3.6.1 gmp/6.1.1 libsigsegv/2.10 lzma/4.32.7 ncurses/6.0 openmpi/2.0.1 py-numpy/1.11.1-openblas sqlite/3.8.5
+ ------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/gcc/7.2.0 --------------------------------------------------------------------------
+ bzip2/1.0.6 mpich/3.2 netlib-lapack/3.6.1 openmpi/1.10.2 pkg-config/0.29.2 py-numpy/1.13.1-openblas py-pyparsing/2.2.0 py-setuptools/35.0.2 python/2.7.14 sqlite/3.20.0
+ cmake/3.9.4 ncurses/6.0 openblas/0.2.20 openssl/1.0.2k py-appdirs/1.4.3 py-packaging/16.8 py-scipy/0.19.1-openblas py-six/1.10.0 readline/7.0 zlib/1.2.11
- ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
- gcc/6.2.0 (L)
+ ---------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/Core ----------------------------------------------------------------------------
+ gcc/7.2.0 (L)
-The same holds true for the ``MPI`` part of the stack, that you can enable by loading
-either ``mpich`` or ``openmpi``. The nice features of LMod will become evident
-once you'll try switching among different stacks:
+ Where:
+ L: Module is loaded
+
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
+
+The same holds true also for the ``MPI`` part, that you can enable by loading
+either ``mpich`` or ``openmpi``. Let's start by loading ``mpich``:
.. code-block:: console
- $ module load mpich
- $ module avail
+ root@module-file-tutorial:/# module load mpich
+ root@module-file-tutorial:/# module avail
- ----------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/mpich/3.2-5n5xoep/gcc/6.2.0 ------------------------------------------------------------
+ ---------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/mpich/3.2-7gxffhv/gcc/7.2.0 -----------------------------------------------------------------
netlib-scalapack/2.0.2-netlib netlib-scalapack/2.0.2-openblas (D)
- -------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/gcc/6.2.0 ---------------------------------------------------------------------
- binutils/2.27 curl/7.50.3 hwloc/1.11.4 libtool/2.4.6 lzo/2.09 netlib-lapack/3.6.1 openssl/1.0.2j py-scipy/0.18.1-openblas util-macros/1.19.0
- bison/3.0.4 expat/2.2.0 libarchive/3.2.1 libxml2/2.9.4 m4/1.4.17 nettle/3.2 pkg-config/0.29.1 py-setuptools/25.2.0 xz/5.2.2
- bzip2/1.0.6 flex/2.6.0 libpciaccess/0.13.4 lz4/131 mpich/3.2 (L) openblas/0.2.19 py-nose/1.3.7 python/2.7.12 zlib/1.2.8
- cmake/3.6.1 gmp/6.1.1 libsigsegv/2.10 lzma/4.32.7 ncurses/6.0 openmpi/2.0.1 py-numpy/1.11.1-openblas sqlite/3.8.5
+ ------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/gcc/7.2.0 --------------------------------------------------------------------------
+ bzip2/1.0.6 mpich/3.2 (L) netlib-lapack/3.6.1 openmpi/1.10.2 pkg-config/0.29.2 py-numpy/1.13.1-openblas py-pyparsing/2.2.0 py-setuptools/35.0.2 python/2.7.14 sqlite/3.20.0
+ cmake/3.9.4 ncurses/6.0 openblas/0.2.20 openssl/1.0.2k py-appdirs/1.4.3 py-packaging/16.8 py-scipy/0.19.1-openblas py-six/1.10.0 readline/7.0 zlib/1.2.11
- ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
- gcc/6.2.0 (L)
+ ---------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/Core ----------------------------------------------------------------------------
+ gcc/7.2.0 (L)
- $ module load openblas netlib-scalapack/2.0.2-openblas
- $ module list
+ Where:
+ L: Module is loaded
+ D: Default Module
+
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
+
+
+ root@module-file-tutorial:/# module load openblas netlib-scalapack/2.0.2-openblas
+ root@module-file-tutorial:/# module list
Currently Loaded Modules:
- 1) gcc/6.2.0 2) mpich/3.2 3) openblas/0.2.19 4) netlib-scalapack/2.0.2-openblas
+ 1) gcc/7.2.0 2) mpich/3.2 3) openblas/0.2.20 4) netlib-scalapack/2.0.2-openblas
- $ module load openmpi
+At this point we can showcase the improved consistency that a hierarchical layout provides
+over a non-hierarchical one:
+
+.. code-block:: console
- Lmod is automatically replacing "mpich/3.2" with "openmpi/2.0.1"
+ root@module-file-tutorial:/# module load openmpi
+ Lmod is automatically replacing "mpich/3.2" with "openmpi/1.10.2".
- Due to MODULEPATH changes the following have been reloaded:
+ Due to MODULEPATH changes, the following have been reloaded:
1) netlib-scalapack/2.0.2-openblas
-This layout is already a great improvement over the usual non-hierarchical layout,
-but it still has an asymmetry: ``LAPACK`` providers are semantically the same as ``MPI``
-providers, but they are still not part of the hierarchy. We'll see a possible solution
-next.
+``Lmod`` took care of swapping the MPI provider for us, and it also substituted the
+``netlib-scalapack`` module to conform to the change in the MPI.
+In this way we can't accidentally pull-in two different MPI providers at the
+same time or load a module file for a package linked to ``openmpi`` when ``mpich`` is also loaded.
+Consistency for compilers and MPI is ensured by the tool.
-.. Activate lmod and turn the previous modifications into lmod:
- Add core compilers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Extend the hierarchy to other virtual providers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Add LAPACK to the hierarchy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The hierarchy just shown is already a great improvement over non-hierarchical layouts,
+but it still has an asymmetry: ``LAPACK`` providers cover the same semantic role
+as ``MPI`` providers, but yet they are not part of the hierarchy.
+
+To be more practical, this means that although we have gained an improved consistency in
+our environment when it comes to ``MPI``, we still have the same problems as we had before
+for ``LAPACK`` implementations:
+
+.. code-block:: console
+
+ root@module-file-tutorial:/# module list
+
+ Currently Loaded Modules:
+ 1) gcc/7.2.0 2) openblas/0.2.20 3) openmpi/1.10.2 4) netlib-scalapack/2.0.2-openblas
+
+ root@module-file-tutorial:/# module load netlib-scalapack/2.0.2-netlib
+ Autoloading netlib-lapack/3.6.1
-.. warning::
- This is an experimental feature
- Having a hierarchy deeper than ``Core``/``Compiler``/``MPI`` is an experimental
- feature, still not fully supported by ``module spider``,
- see `here <https://github.com/TACC/Lmod/issues/114>`_. Furthermore its use
- with hierarchies more complex than ``Core``/``Compiler``/``MPI``/``LAPACK``
- has not been thoroughly tested in production environments.
+ The following have been reloaded with a version change:
+ 1) netlib-scalapack/2.0.2-openblas => netlib-scalapack/2.0.2-netlib
-Spack permits you to generate Lua hierarchical module files where users
-can add an arbitrary list of virtual providers to the triplet
-``Core``/``Compiler``/``MPI``. A configuration file like:
+ root@module-file-tutorial:/# module list
+
+ Currently Loaded Modules:
+ 1) gcc/7.2.0 2) openblas/0.2.20 3) openmpi/1.10.2 4) netlib-lapack/3.6.1 5) netlib-scalapack/2.0.2-netlib
+
+Hierarchies that are deeper than ``Core``/``Compiler``/``MPI`` are
+probably still considered "unusual" or "impractical" at many sites, mainly because
+module files are written manually and keeping track of the combinations
+among multiple providers quickly becomes quite involved.
+
+For instance, having both ``MPI`` and ``LAPACK`` in the hierarchy
+means we must classify software into one of four categories:
+
+ #. Software that doesn't depend on ``MPI`` or ``LAPACK``
+ #. Software that depends only on ``MPI``
+ #. Software that depends only on ``LAPACK``
+ #. Software that depends on both
+
+to decide when to show it to the user. The situation becomes more involved as the number of virtual
+dependencies in the hierarchy increases.
+
+We can take advantage of the DAG that Spack maintains for the installed software and solve
+this combinatorial problem in a clean and automated way.
+In some sense Spack's ability to manage this combinatorial complexity makes deeper
+hierarchies feasible.
+
+Coming back to our example, let's add ``lapack`` to the hierarchy and remove any remaining suffix:
.. code-block:: yaml
:emphasize-lines: 9
@@ -892,7 +1257,7 @@ can add an arbitrary list of virtual providers to the triplet
- lmod
lmod:
core_compilers:
- - 'gcc@4.8'
+ - 'gcc@5.4.0'
hierarchy:
- mpi
- lapack
@@ -900,7 +1265,7 @@ can add an arbitrary list of virtual providers to the triplet
whitelist:
- gcc
blacklist:
- - '%gcc@4.8'
+ - '%gcc@5.4.0'
- readline
all:
filter:
@@ -922,63 +1287,255 @@ can add an arbitrary list of virtual providers to the triplet
SLURM_MPI_TYPE: pmi2
OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
-will add ``lapack`` providers to the mix. After the usual regeneration of module files:
+After module files have been regenerated as usual:
.. code-block:: console
- $ module purge
- $ spack module refresh --module-type lmod --delete-tree -y
+ root@module-file-tutorial:/# module purge
+
+ root@module-file-tutorial:/# spack module refresh --delete-tree -y -m lmod
==> Regenerating lmod module files
-you will have something like:
+we can see that now we have additional components in the hierarchy:
.. code-block:: console
- $ module load gcc
- $ module load openblas
- $ module load openmpi
- $ module avail
+ root@module-file-tutorial:/# module load gcc
+ root@module-file-tutorial:/# module load openblas
+ root@module-file-tutorial:/# module avail
+
+ ------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/openblas/0.2.20-kvddide/gcc/7.2.0 --------------------------------------------------------------
+ py-numpy/1.13.1 py-scipy/0.19.1
+
+ ------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/gcc/7.2.0 --------------------------------------------------------------------------
+ bzip2/1.0.6 mpich/3.2 netlib-lapack/3.6.1 openmpi/1.10.2 pkg-config/0.29.2 py-packaging/16.8 py-setuptools/35.0.2 python/2.7.14 sqlite/3.20.0
+ cmake/3.9.4 ncurses/6.0 openblas/0.2.20 (L) openssl/1.0.2k py-appdirs/1.4.3 py-pyparsing/2.2.0 py-six/1.10.0 readline/7.0 zlib/1.2.11
+
+ ---------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/Core ----------------------------------------------------------------------------
+ gcc/7.2.0 (L)
+
+ Where:
+ L: Module is loaded
+
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
+
- --------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/openblas/0.2.19-js33umc/openmpi/2.0.1-s3qbtby/gcc/6.2.0 ----------------------------------------------
+ root@module-file-tutorial:/# module load openmpi
+ root@module-file-tutorial:/# module avail
+
+ -------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/openmpi/1.10.2-ufw7pdi/openblas/0.2.20-kvddide/gcc/7.2.0 --------------------------------------------------
netlib-scalapack/2.0.2
- -------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/openblas/0.2.19-js33umc/gcc/6.2.0 ---------------------------------------------------------
- py-numpy/1.11.1 py-scipy/0.18.1
+ ------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/openblas/0.2.20-kvddide/gcc/7.2.0 --------------------------------------------------------------
+ py-numpy/1.13.1 py-scipy/0.19.1
+
+ ------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/gcc/7.2.0 --------------------------------------------------------------------------
+ bzip2/1.0.6 mpich/3.2 netlib-lapack/3.6.1 openmpi/1.10.2 (L) pkg-config/0.29.2 py-packaging/16.8 py-setuptools/35.0.2 python/2.7.14 sqlite/3.20.0
+ cmake/3.9.4 ncurses/6.0 openblas/0.2.20 (L) openssl/1.0.2k py-appdirs/1.4.3 py-pyparsing/2.2.0 py-six/1.10.0 readline/7.0 zlib/1.2.11
- -------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/gcc/6.2.0 ---------------------------------------------------------------------
- binutils/2.27 curl/7.50.3 hwloc/1.11.4 libtool/2.4.6 lzo/2.09 netlib-lapack/3.6.1 openssl/1.0.2j python/2.7.12 zlib/1.2.8
- bison/3.0.4 expat/2.2.0 libarchive/3.2.1 libxml2/2.9.4 m4/1.4.17 nettle/3.2 pkg-config/0.29.1 sqlite/3.8.5
- bzip2/1.0.6 flex/2.6.0 libpciaccess/0.13.4 lz4/131 mpich/3.2 openblas/0.2.19 (L) py-nose/1.3.7 util-macros/1.19.0
- cmake/3.6.1 gmp/6.1.1 libsigsegv/2.10 lzma/4.32.7 ncurses/6.0 openmpi/2.0.1 (L) py-setuptools/25.2.0 xz/5.2.2
+ ---------------------------------------------------------------------------- /usr/local/share/spack/lmod/linux-ubuntu16.04-x86_64/Core ----------------------------------------------------------------------------
+ gcc/7.2.0 (L)
- ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
- gcc/6.2.0 (L)
+ Where:
+ L: Module is loaded
-Now both the ``MPI`` and the ``LAPACK`` providers are handled by LMod as hierarchies:
+ Use "module spider" to find all possible modules.
+ Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
+
+Both ``MPI`` and ``LAPACK`` providers will now benefit from the same safety features:
.. code-block:: console
- $ module load py-numpy netlib-scalapack
- $ module load mpich
+ root@module-file-tutorial:/# module load py-numpy netlib-scalapack
+ root@module-file-tutorial:/# module load mpich
- Lmod is automatically replacing "openmpi/2.0.1" with "mpich/3.2"
+ Lmod is automatically replacing "openmpi/1.10.2" with "mpich/3.2".
- Due to MODULEPATH changes the following have been reloaded:
+ Due to MODULEPATH changes, the following have been reloaded:
1) netlib-scalapack/2.0.2
- $ module load netlib-lapack
+ root@module-file-tutorial:/# module load netlib-lapack
- Lmod is automatically replacing "openblas/0.2.19" with "netlib-lapack/3.6.1"
+ Lmod is automatically replacing "openblas/0.2.20" with "netlib-lapack/3.6.1".
Inactive Modules:
1) py-numpy
- Due to MODULEPATH changes the following have been reloaded:
+ Due to MODULEPATH changes, the following have been reloaded:
1) netlib-scalapack/2.0.2
-making the use of tags to differentiate them unnecessary.
-Note that because we only compiled ``py-numpy`` with ``openblas`` the module
+Because we only compiled ``py-numpy`` with ``openblas`` the module
is made inactive when we switch the ``LAPACK`` provider. The user
-environment will now be consistent by design!
+environment is now consistent by design!
+
+----------------------
+Working with templates
+----------------------
+
+As briefly mentioned in the introduction, Spack uses `Jinja2 <http://jinja.pocoo.org/docs/2.9/>`_
+to generate each individual module file.
+This means that you have all of its flexibility and power when it comes to
+customizing what gets generated!
+
+^^^^^^^^^^^^^^^^^^^^^
+Module file templates
+^^^^^^^^^^^^^^^^^^^^^
+
+The templates that Spack uses to generate module files are stored in the
+``templates/module`` directory, and they all share the same common structure.
+Usually, they start with a header that identifies the type of
+module being generated. In the case of hierarchical module files it's:
+
+.. literalinclude:: ../../../templates/modules/modulefile.lua
+ :language: jinja
+ :lines: 1-6
+
+The statements within double curly brackets ``{{ ... }}`` denote
+`expressions <http://jinja.pocoo.org/docs/2.9/templates/#expressions>`_
+that will be evaluated and substituted at module generation time.
+The rest of the file is then divided into
+`blocks <http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance>`_
+that can be overridden or extended by users, if need be.
+`Control structures <http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures>`_
+, delimited by ``{% ... %}``,
+are also permitted in the template language:
+
+.. literalinclude:: ../../../templates/modules/modulefile.lua
+ :language: jinja
+ :lines: 73-88
+
+The locations where Spack looks for templates are specified
+in ``config.yaml``:
+
+.. literalinclude:: ../../../etc/spack/defaults/config.yaml
+ :language: yaml
+ :lines: 21-24
+
+and can be extended by users to employ custom templates, as we'll see next.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Extend the default templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let's assume one of our software is protected by group membership:
+allowed users belong to the same linux group, and access is granted at group level.
+Wouldn't it be nice if people that are not
+yet entitled to use it could receive a helpful message at module load time
+that tells them who to contact in your organization to be inserted in the group?
+
+To automate the generation of module files with such site-specific behavior
+we'll start by extending the list of locations where Spack looks for module
+files. Let's create the file ``~/.spack/config.yaml`` with the content:
+
+.. code-block:: yaml
+
+ config:
+ template_dirs:
+ - $HOME/.spack/templates
+
+This tells Spack to also search another location when looking for template files.
+Next, we need to create our custom template extension in the folder listed above:
+
+.. code-block:: jinja
+
+ {% extends "modules/modulefile.lua" %}
+ {% block footer %}
+ -- Access is granted only to specific groups
+ if not isDir("{{ spec.prefix }}") then
+ LmodError (
+ "You don't have the necessary rights to run \"{{ spec.name }}\".\n\n",
+ "\tPlease write an e-mail to 1234@foo.com if you need further information on how to get access to it.\n"
+ )
+ end
+ {% endblock %}
+
+Let's name this file ``group-restricted.lua``. The line:
+
+.. code-block:: jinja
+
+ {% extends "modules/modulefile.lua" %}
+
+tells Jinja2 that we are reusing the standard template for hierarchical module files.
+The section:
+
+.. code-block:: jinja
+
+ {% block footer %}
+ -- Access is granted only to specific groups
+ if not isDir("{{ spec.prefix }}") then
+ LmodError (
+ "You don't have the necessary rights to run \"{{ spec.name }}\".\n\n",
+ "\tPlease write an e-mail to 1234@foo.com if you need further information on how to get access to it.\n"
+ )
+ end
+ {% endblock %}
+
+overrides the ``footer`` block.
+Finally, we need to add a couple of lines in ``modules.yaml`` to tell Spack which specs
+need to use the new custom template. For the sake of illustration let's assume
+it's ``netlib-scalapack``:
+
+.. code-block:: yaml
+ :emphasize-lines: 35-36
+
+ modules:
+ enable::
+ - lmod
+ lmod:
+ core_compilers:
+ - 'gcc@5.4.0'
+ hierarchy:
+ - mpi
+ - lapack
+ hash_length: 0
+ whitelist:
+ - gcc
+ blacklist:
+ - '%gcc@5.4.0'
+ - readline
+ all:
+ filter:
+ environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+ environment:
+ set:
+ '${PACKAGE}_ROOT': '${PREFIX}'
+ gcc:
+ environment:
+ set:
+ CC: gcc
+ CXX: g++
+ FC: gfortran
+ F90: gfortran
+ F77: gfortran
+ openmpi:
+ environment:
+ set:
+ SLURM_MPI_TYPE: pmi2
+ OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
+ netlib-scalapack:
+ template: 'group-restricted.lua'
+
+If we regenerate the module files one last time:
+
+.. code-block:: console
+
+ root@module-file-tutorial:/# spack module refresh -y -m lmod netlib-scalapack
+ ==> Regenerating lmod module files
+
+we'll find the following at the end of each ``netlib-scalapack`` module file:
+
+.. code-block:: lua
+
+ -- Access is granted only to specific groups
+ if not isDir("/usr/local/opt/spack/linux-ubuntu16.04-x86_64/gcc-7.2.0/netlib-scalapack-2.0.2-ax6aza6vyepceyr3fihewp7rbr2vp7ym") then
+ LmodError (
+ "You don't have the necessary rights to run \"netlib-scalapack\".\n\n",
+ "\tPlease write an e-mail to 1234@foo.com if you need further information on how to get access to it.\n"
+ )
+ end
+
+and every user that doesn't have access to the software will now be redirected to
+the right e-mail address where to ask for it!
diff --git a/lib/spack/docs/workflows.rst b/lib/spack/docs/workflows.rst
index 140c0e5649..4c674f92e4 100644
--- a/lib/spack/docs/workflows.rst
+++ b/lib/spack/docs/workflows.rst
@@ -1106,6 +1106,8 @@ The main points that are implemented below:
- make -j 2
- make test
+.. _workflow_create_docker_image:
+
-----------------------------------
Using Spack to Create Docker Images
-----------------------------------
diff --git a/share/spack/docs/docker/module-file-tutorial/Dockerfile b/share/spack/docs/docker/module-file-tutorial/Dockerfile
new file mode 100644
index 0000000000..a012492a98
--- /dev/null
+++ b/share/spack/docs/docker/module-file-tutorial/Dockerfile
@@ -0,0 +1,52 @@
+FROM ubuntu:16.04
+
+# General environment for docker
+ENV DEBIAN_FRONTEND=noninteractive \
+ SPACK_ROOT=/usr/local \
+ FORCE_UNSAFE_CONFIGURE=1
+
+# Install system packages
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+ autoconf \
+ build-essential \
+ ca-certificates \
+ coreutils \
+ curl man less \
+ emacs-nox vim nano \
+ git \
+ openmpi-bin openmpi-common libopenmpi-dev \
+ python \
+ unzip \
+ && rm -rf /var/lib/apt/lists/*
+
+# Load spack environment on login
+COPY spack.sh /etc/profile
+
+# Install spack
+RUN curl -s -L https://api.github.com/repos/spack/spack/tarball/develop \
+ | tar xzC $SPACK_ROOT --strip 1
+
+# Copy configuration for external packages
+COPY packages.yaml $SPACK_ROOT/etc/spack/
+
+# Build lmod
+RUN spack install lmod && spack clean -a
+
+# Build a compiler
+RUN spack install gcc@7.2.0 && spack clean -a
+RUN /bin/bash -l -c ' \
+ spack load gcc@7.2.0 \
+ && spack compiler add'
+
+# Build the software on top of the compiler
+RUN spack install netlib-scalapack ^openmpi ^openblas %gcc@7.2.0 \
+ && spack install netlib-scalapack ^mpich ^openblas %gcc@7.2.0 \
+ && spack install netlib-scalapack ^openmpi ^netlib-lapack %gcc@7.2.0 \
+ && spack install netlib-scalapack ^mpich ^netlib-lapack %gcc@7.2.0 \
+ && spack install py-scipy ^openblas \
+ && spack clean -a
+
+# image run hook: the -l will make sure /etc/profile environments are loaded
+CMD /bin/bash -l
+
diff --git a/share/spack/docs/docker/module-file-tutorial/packages.yaml b/share/spack/docs/docker/module-file-tutorial/packages.yaml
new file mode 100644
index 0000000000..8e3971e61f
--- /dev/null
+++ b/share/spack/docs/docker/module-file-tutorial/packages.yaml
@@ -0,0 +1,9 @@
+packages:
+ git:
+ buildable: False
+ paths:
+ git@2.9.4: /usr
+ openmpi:
+ buildable: False
+ paths:
+ openmpi@1.10.2: /usr
diff --git a/share/spack/docs/docker/module-file-tutorial/spack.sh b/share/spack/docs/docker/module-file-tutorial/spack.sh
new file mode 100644
index 0000000000..54d095c717
--- /dev/null
+++ b/share/spack/docs/docker/module-file-tutorial/spack.sh
@@ -0,0 +1,8 @@
+source $SPACK_ROOT/share/spack/setup-env.sh
+
+LMOD_DIR=$(spack location -i lmod)
+
+if [[ $LMOD_DIR ]] ; then
+ source ${LMOD_DIR}/lmod/lmod/init/bash
+ source $SPACK_ROOT/share/spack/setup-env.sh
+fi
generated by cgit v1.2.3-60-g2f50 (git 2.42.0) at 2024-07-02 15:08:51 +0000