Nothing Special   »   [go: up one dir, main page]
Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Add embedded compiler-explorer example #444

Draft
wants to merge 8 commits into
base: main
Choose a base branch
from
Draft

Add embedded compiler-explorer example #444

wants to merge 8 commits into from
+72 −1

Conversation

cz4rs
Copy link
Contributor
@cz4rs cz4rs commented Jul 25, 2023 •
edited
Loading

This is not mergeable, just providing actual examples for the next documentation session.

Sphinx allows for html injection with .. raw:: html. That's probably the easiest way to use Share -> Embed in iframe functionality available in compiler-explorer.

See initialization example below (our current approach is kept for comparison):

image

Code used:

.. raw:: html

  <iframe width="800px" height="300px" src="https://godbolt.org/e?hideEditorToolbars=true#g:!((g:!((g:!((h:codeEditor,i:(filename:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,selection:(endColumn:1,endLineNumber:9,positionColumn:1,positionLineNumber:9,selectionStartColumn:1,selectionStartLineNumber:9,startColumn:1,startLineNumber:9),source:'%23include+%3CKokkos_Core.hpp%3E%0A%0Aint+main(int+argc,+char**+argv)+%7B%0A++Kokkos::initialize(argc,+argv)%3B%0A++Kokkos::View%3Cdouble*%3E+my_view(%22my_view%22,+10)%3B%0A++Kokkos::finalize()%3B%0A++//+my_view+destructor+called+after+Kokkos::finalize+!!%0A%7D%0A'),l:'5',n:'0',o:'C%2B%2B+source+%231',t:'0')),k:50,l:'4',m:100,n:'0',o:'',s:0,t:'0'),(g:!((h:compiler,i:(compiler:clang1600,deviceViewOpen:'1',filters:(b:'0',binary:'1',binaryObject:'1',commentOnly:'0',debugCalls:'1',demangle:'0',directives:'0',execute:'1',intel:'0',libraryCode:'0',trim:'1'),flagsViewOpen:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,libs:!((name:kokkos,ver:'4100')),options:'',overrides:!(),selection:(endColumn:1,endLineNumber:1,positionColumn:1,positionLineNumber:1,selectionStartColumn:1,selectionStartLineNumber:1,startColumn:1,startLineNumber:1),source:1),l:'5',n:'0',o:'+x86-64+clang+16.0.0+(Editor+%231)',t:'0')),header:(),k:50,l:'4',n:'0',o:'',s:0,t:'0')),l:'2',n:'0',o:'',t:'0')),version:4"></iframe>

Note: there is some customization available when generating the link (Read only, Hide editor toolbars). Further configuration is contained in the generated link.

@cz4rs
Copy link
Contributor Author
cz4rs commented Jul 31, 2023 •
edited
Loading

Another way to enforce that the code snippets in documentation are compiling: literal include (2e525e9).
If we supplement this with an autogenerated Edit on Compiler Explorer button, we might have a quicker, more lightweight option than embedding CE directly.

image

@cz4rs cz4rs force-pushed the embedded-compiler-explorer branch from 702afc5 to 2e525e9 Compare July 31, 2023 10:47
@crtrott
Copy link
Member
crtrott commented Aug 9, 2023

Hm, interesting, I was thinking of much simpler: i.e. have a code snippet and then a short link to godbolt. Obviously that wouldn't guarantee that they are the same thing.

@ajpowelsnl
Copy link
Contributor

TODO:

  • Cezary: Fix up example for Wed. meeting to demo for the team
  • Discuss in Wed. meeting if we want Compiler Explorer (CE) examples to simply compile, or also generate run-able executable;
    • Simple CE examples (for Documentation, etc.) into existing or new repos?
    • Integrate CE examples into training, teaching & demos?

cz4rs
cz4rs commented Oct 25, 2023
View reviewed changes
docs/source/API/core/parallel-dispatch/parallel_for.rst
Comment on lines +87 to +89
.. raw:: html

<a href="https://godbolt.org/z/q9h339vob" target="_blank">Edit on Compiler Explorer</a>
Copy link
Contributor Author

Choose a reason for hiding this comment

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

code-block above + a manually created shortlink to Compiler Explorer:
image

cz4rs
cz4rs commented Oct 25, 2023
View reviewed changes
docs/source/API/core/parallel-dispatch/parallel_for.rst
Comment on lines +94 to +97
.. ceinclude:: ../../../../../kokkos/example/tutorial/01_hello_world_lambda/hello_world_lambda.cpp
:language: cpp
:start-after: Kokkos::initialize
:end-before: Kokkos::finalize
Copy link
Contributor Author
@cz4rs cz4rs Oct 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

helo_world_lambda.cpp + an auto-generated link using clientstate API:

image

See live version.

See ceinclude.py for extension details.

Copy link
Contributor

Choose a reason for hiding this comment

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

Given the number of comments in this file, I would rather not include that one specifically. Other than that, it's a good idea to use examples we run through our CI. I could see that we just reduce the verbosity in these files and refer to kokkos-tutorials for more extensive tutorials.

@ajpowelsnl
Copy link
Contributor

@cz4rs , @masterleinad - What do we need to do next to work towards completion of this issue?

@cz4rs
Copy link
Contributor Author
cz4rs commented Jan 10, 2024

@cz4rs , @masterleinad - What do we need to do next to work towards completion of this issue?

Hi @ajpowelsnl! As far as I know there was no decision (or even major discussion) regarding how much integration and how many changes we want to do.

Assuming we just want to update existing snippets with Edit on Compiler Explorer button, we have two options:

  • add manually created shortlinks - Add embedded compiler-explorer example #444 (comment)
    • not great, not terrible - this approach involves manual work and the shortlinks are permanent so we have to remember to update them
  • add auto-generated links - Add embedded compiler-explorer example #444 (comment)
    • replace .. code-block:: cpp with our custom extension (e.g. .. ce-code-block:: cpp) that will wrap the code-block and add Compiler Explorer link
    • this extension will be similar to the ceinclude.py from this PR, only based on code-block instead of literalinclude

IMHO the second option is clearly better (less maintenance!), with the only downside being that the generated links are quite long and ugly:

https://godbolt.org/clientstate/eyJzZXNzaW9ucyI6IFt7ImlkIjogMSwgImxhbmd1YWdlIjogImMrKyIsICJzb3VyY2UiOiAiLy9ASEVBREVSXG4vLyAqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKipcbi8vXG4vLyAgICAgICAgICAgICAgICAgICAgICAgIEtva2tvcyB2LiA0LjBcbi8vICAgICAgIENvcHlyaWdodCAoMjAyMikgTmF0aW9uYWwgVGVjaG5vbG9neSAmIEVuZ2luZWVyaW5nXG4vLyAgICAgICAgICAgICAgIFNvbHV0aW9ucyBvZiBTYW5kaWEsIExMQyAoTlRFU1MpLlxuLy9cbi8vIFVuZGVyIHRoZSB0ZXJtcyBvZiBDb250cmFjdCBERS1OQTAwMDM1MjUgd2l0aCBOVEVTUyxcbi8vIHRoZSBVLlMuIEdvdmVybm1lbnQgcmV0YWlucyBjZXJ0YWluIHJpZ2h0cyBpbiB0aGlzIHNvZnR3YXJlLlxuLy9cbi8vIFBhcnQgb2YgS29ra29zLCB1bmRlciB0aGUgQXBhY2hlIExpY2Vuc2UgdjIuMCB3aXRoIExMVk0gRXhjZXB0aW9ucy5cbi8vIFNlZSBodHRwczovL2tva2tvcy5vcmcvTElDRU5TRSBmb3IgbGljZW5zZSBpbmZvcm1hdGlvbi5cbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wIFdJVEggTExWTS1leGNlcHRpb25cbi8vXG4vL0BIRUFERVJcblxuI2luY2x1ZGUgPEtva2tvc19Db3JlLmhwcD5cbiNpbmNsdWRlIDxjc3RkaW8-XG4jaW5jbHVkZSA8dHlwZWluZm8-XG5cbi8vXG4vLyBcIkhlbGxvIHdvcmxkXCIgcGFyYWxsZWxfZm9yIGV4YW1wbGU6XG4vLyAgIDEuIFN0YXJ0IHVwIEtva2tvc1xuLy8gICAyLiBFeGVjdXRlIGEgcGFyYWxsZWwgZm9yIGxvb3AgaW4gdGhlIGRlZmF1bHQgZXhlY3V0aW9uIHNwYWNlLFxuLy8gICAgICB1c2luZyBhIEMrKzExIGxhbWJkYSB0byBkZWZpbmUgdGhlIGxvb3AgYm9keVxuLy8gICAzLiBTaHV0IGRvd24gS29ra29zXG4vL1xuLy8gVGhpcyBleGFtcGxlIG9ubHkgYnVpbGRzIGlmIEMrKzExIGlzIGVuYWJsZWQuICBDb21wYXJlIHRoaXMgZXhhbXBsZVxuLy8gdG8gMDFfaGVsbG9fd29ybGQsIHdoaWNoIHVzZXMgZnVuY3RvcnMgKGV4cGxpY2l0bHkgZGVmaW5lZCBjbGFzc2VzKVxuLy8gdG8gZGVmaW5lIHRoZSBsb29wIGJvZHkgb2YgdGhlIHBhcmFsbGVsX2Zvci4gIEJvdGggZnVuY3RvcnMgYW5kXG4vLyBsYW1iZGFzIGhhdmUgdGhlaXIgcGxhY2VzLlxuLy9cblxuaW50IG1haW4oaW50IGFyZ2MsIGNoYXIqIGFyZ3ZbXSkge1xuICAvLyBZb3UgbXVzdCBjYWxsIGluaXRpYWxpemUoKSBiZWZvcmUgeW91IG1heSBjYWxsIEtva2tvcy5cbiAgLy9cbiAgLy8gV2l0aCBubyBhcmd1bWVudHMsIHRoaXMgaW5pdGlhbGl6ZXMgdGhlIGRlZmF1bHQgZXhlY3V0aW9uIHNwYWNlXG4gIC8vIChhbmQgcG90ZW50aWFsbHkgaXRzIGhvc3QgZXhlY3V0aW9uIHNwYWNlKSB3aXRoIGRlZmF1bHRcbiAgLy8gcGFyYW1ldGVycy4gIFlvdSBtYXkgYWxzbyBwYXNzIGluIGFyZ2MgYW5kIGFyZ3YsIGFuYWxvZ291c2x5IHRvXG4gIC8vIE1QSV9Jbml0KCkuICBJdCByZWFkcyBhbmQgcmVtb3ZlcyBjb21tYW5kLWxpbmUgYXJndW1lbnRzIHRoYXRcbiAgLy8gc3RhcnQgd2l0aCBcIi0ta29ra29zLVwiLlxuICBLb2trb3M6OmluaXRpYWxpemUoYXJnYywgYXJndik7XG5cbiAgLy8gUHJpbnQgdGhlIG5hbWUgb2YgS29ra29zJyBkZWZhdWx0IGV4ZWN1dGlvbiBzcGFjZS4gIFdlJ3JlIHVzaW5nXG4gIC8vIHR5cGVpZCBoZXJlLCBzbyB0aGUgbmFtZSBtaWdodCBnZXQgYSBiaXQgbWFuZ2xlZCBieSB0aGUgbGlua2VyLFxuICAvLyBidXQgeW91IHNob3VsZCBzdGlsbCBiZSBhYmxlIHRvIGZpZ3VyZSBvdXQgd2hhdCBpdCBpcy5cbiAgcHJpbnRmKFwiSGVsbG8gV29ybGQgb24gS29ra29zIGV4ZWN1dGlvbiBzcGFjZSAlc1xcblwiLFxuICAgICAgICAgdHlwZWlkKEtva2tvczo6RGVmYXVsdEV4ZWN1dGlvblNwYWNlKS5uYW1lKCkpO1xuXG4gIC8vIFJ1biBsYW1iZGEgb24gdGhlIGRlZmF1bHQgS29ra29zIGV4ZWN1dGlvbiBzcGFjZSBpbiBwYXJhbGxlbCxcbiAgLy8gd2l0aCBhIHBhcmFsbGVsIGZvciBsb29wIGNvdW50IG9mIDE1LiAgVGhlIGxhbWJkYSdzIGFyZ3VtZW50IGlzXG4gIC8vIGFuIGludGVnZXIgd2hpY2ggaXMgdGhlIHBhcmFsbGVsIGZvcidzIGxvb3AgaW5kZXguICBBcyB5b3UgbGVhcm5cbiAgLy8gYWJvdXQgZGlmZmVyZW50IGtpbmRzIG9mIHBhcmFsbGVsaXNtLCB5b3Ugd2lsbCBmaW5kIG91dCB0aGF0XG4gIC8vIHRoZXJlIGFyZSBvdGhlciB2YWxpZCBhcmd1bWVudCB0eXBlcyBhcyB3ZWxsLlxuICAvL1xuICAvLyBGb3IgYSBzaW5nbGUgbGV2ZWwgb2YgcGFyYWxsZWxpc20sIHdlIHByZWZlciB0aGF0IHlvdSB1c2UgdGhlXG4gIC8vIEtPS0tPU19MQU1CREEgbWFjcm8uICBJZiBDVURBIGlzIGRpc2FibGVkLCB0aGlzIGp1c3QgdHVybnMgaW50b1xuICAvLyBbPV0uICBUaGF0IGNhcHR1cmVzIHZhcmlhYmxlcyBmcm9tIHRoZSBzdXJyb3VuZGluZyBzY29wZSBieVxuICAvLyB2YWx1ZS4gIERvIE5PVCBjYXB0dXJlIHRoZW0gYnkgcmVmZXJlbmNlISAgSWYgQ1VEQSBpcyBlbmFibGVkLFxuICAvLyB0aGlzIG1hY3JvIG1heSBoYXZlIGEgc3BlY2lhbCBkZWZpbml0aW9uIHRoYXQgbWFrZXMgdGhlIGxhbWJkYVxuICAvLyB3b3JrIGNvcnJlY3RseSB3aXRoIENVREEuICBDb21wYXJlIHRvIHRoZSBLT0tLT1NfSU5MSU5FX0ZVTkNUSU9OXG4gIC8vIG1hY3JvLCB3aGljaCBoYXMgYSBzcGVjaWFsIG1lYW5pbmcgaWYgQ1VEQSBpcyBlbmFibGVkLlxuICAvL1xuICAvLyBUaGUgZm9sbG93aW5nIHBhcmFsbGVsX2ZvciB3b3VsZCBsb29rIGxpa2UgdGhpcyBpZiB3ZSB3ZXJlIHVzaW5nXG4gIC8vIE9wZW5NUCBieSBpdHNlbGYsIGluc3RlYWQgb2YgS29ra29zOlxuICAvL1xuICAvLyAjcHJhZ21hIG9tcCBwYXJhbGxlbCBmb3JcbiAgLy8gZm9yIChpbnQgaSA9IDA7IGkgPCAxNTsgKytpKSB7XG4gIC8vICAgcHJpbnRmIChcIkhlbGxvIGZyb20gaSA9ICVpXFxuXCIsIGkpO1xuICAvLyB9XG4gIC8vXG4gIC8vIFlvdSBtYXkgbm90aWNlIHRoYXQgdGhlIHByaW50ZWQgbnVtYmVycyBkbyBub3QgcHJpbnQgb3V0IGluXG4gIC8vIG9yZGVyLiAgUGFyYWxsZWwgZm9yIGxvb3BzIG1heSBleGVjdXRlIGluIGFueSBvcmRlci5cbiAgLy8gV2UgYWxzbyBuZWVkIHRvIHByb3RlY3QgdGhlIHVzYWdlIG9mIGEgbGFtYmRhIGFnYWluc3QgY29tcGlsaW5nXG4gIC8vIHdpdGggYSBiYWNrZW5kIHdoaWNoIGRvZXNuJ3Qgc3VwcG9ydCBpdCAoaS5lLiBDdWRhIDYuNS83LjApLlxuI2lmIGRlZmluZWQoS09LS09TX0VOQUJMRV9DWFgxMV9ESVNQQVRDSF9MQU1CREEpXG4gIEtva2tvczo6cGFyYWxsZWxfZm9yKFxuICAgICAgMTUsIEtPS0tPU19MQU1CREEoY29uc3QgaW50IGkpIHtcbiAgLy8gRklYTUVfU1lDTCBuZWVkcyB3b3JrYXJvdW5kIGZvciBwcmludGZcbiNpZm5kZWYgX19TWUNMX0RFVklDRV9PTkxZX19cbiAgICAgICAgLy8gcHJpbnRmIHdvcmtzIGluIGEgQ1VEQSBwYXJhbGxlbCBrZXJuZWw7IHN0ZDo6b3N0cmVhbSBkb2VzIG5vdC5cbiAgICAgICAgcHJpbnRmKFwiSGVsbG8gZnJvbSBpID0gJWlcXG5cIiwgaSk7XG4jZWxzZVxuXHQodm9pZClpO1xuI2VuZGlmXG4gICAgICB9KTtcbiNlbmRpZlxuICAvLyBZb3UgbXVzdCBjYWxsIGZpbmFsaXplKCkgYWZ0ZXIgeW91IGFyZSBkb25lIHVzaW5nIEtva2tvcy5cbiAgS29ra29zOjpmaW5hbGl6ZSgpO1xufVxuIiwgImNvbXBpbGVycyI6IFt7ImlkIjogImcxMzIiLCAib3B0aW9ucyI6ICItTzMiLCAibGlicyI6IFt7Im5hbWUiOiAia29ra29zIiwgInZlciI6ICI0MTAwIn1dfV19XX0=

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@masterleinad masterleinad masterleinad left review comments

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@cz4rs @crtrott @ajpowelsnl @masterleinad