/doc/users-guide/getting-started/

dcurtisatmit commented 2 years ago

In following the instructions for using Cilksan on the getting-started page, I encountered the following error on Ubuntu 20.04:

cilk -Og -g nqueens.c -o nqueens /usr/bin/ld: cannot find -lstdc++ clang-12: error: linker command failed with exit code 1 (use -v to see invocation)

After fumbling around, trying to install libstdc++, which didn't work, I tried apt install g++

and, voila, it compiled!

(Um... why am I seeing sage-licorice??? in my links?!?! could be my error?)

behoppe commented 2 years ago

Thanks, @dcurtisatmit. If you agree, I'd like to merge this issue with #38 and #39. They are all about the Getting started page. Then I propose to rename the merged issue with the URL of that page. That way future comments on the Getting started page will be very easy to add to that designated issue, per #41 (better ways to comment on a page).

(In terms of sage-licorice, that URL will continue to work as long as we use Netlify hosting. So it isn't an error per se. It's just a non-standard way of accessing the website.)

dcurtisatmit commented 2 years ago

If I were receiving emails when you enter comments... I would respond... But, sure, go ahead and merge issues. And I guess we'll all find out how issues should be entered tomorrow.

behoppe commented 2 years ago

I am also merging #64 with this issue. My goal is to hold the "Getting started" page as a coherent issue, rather than breaking apart separate discussion for each error that we find on that one page.

behoppe commented 2 years ago

I just installed v2.0 (using the updated Install page) and I'm following the main Getting Started page. Overall it's great, but I'm tripping over a couple things. @ailiop I think you are the owner of this page?

I installed using the defaults, so my files went into a subfolder OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04/. The Getting Started instructions assume that I did not use the defaults, and that my files are in /opt/opencilk/. When they tell me to clone the tutorial repository, I don't know which folder to use. I recommend that the instructions explicitly guide anyone who followed the defaults, and not assume that such a person can figure out how to translate the instructions to his situation.
It's great that the instructions say they assume clang points to the OpenCilk C compiler at /opt/opencilk/bin/clang. I am not sure how to check this on my system, and I definitely do not know how to fix it if it's wrong. For now, I am able to work around by using ../bin/clang from my 'tutorial` folder.
After those two problems, things went smoothly (except for the Python, per below)

I wonder if we can shorten the Cilkscale section by moving the last two parts to a more advanced article:

Analyzing a region
Scalability benchmarking and visualization

These are much more involved than the earlier steps -- especially the Python. My Python threw an error about missing matplotlib, per below. I know enough about Python to feel that confronting this error does not belong in our Getting Started, but can be saved for a later article.

bruce@bruce-ThinkPad-X1-Yoga-1st:~/OpenCilk/OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04/tutorial$ python3 ../share/Cilkscale_vis/cilkscale.py     -c qsort -b qsort-bench --args 10000000
Namespace(args=['10000000'], cilkscale='qsort', cilkscale_benchmark='qsort-bench', cpu_counts=None, output_csv='out.csv', output_plot='plot.pdf', rows_to_plot='all')
WARNING:../share/Cilkscale_vis/cilkscale.py:matplotlib required to generate plot.

>> STDOUT (qsort 10000000)
<< END STDOUT

>> STDERR (qsort 10000000)
/bin/sh: 1: qsort: not found
<< END STDERR

INFO:runner:Generating scalability data for 2 cpus.
INFO:runner:CILK_NWORKERS=1 taskset -c 0 qsort-bench 10000000
INFO:runner:CILK_NWORKERS=2 taskset -c 0,1 qsort-bench 10000000
Traceback (most recent call last):
  File "../share/Cilkscale_vis/cilkscale.py", line 49, in <module>
    main()
  File "../share/Cilkscale_vis/cilkscale.py", line 36, in main
    run(bin_instrument, bin_bench, bin_args, out_csv, cpu_counts)
  File "/home/bruce/OpenCilk/OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04/share/Cilkscale_vis/runner.py", line 118, in run
    with open(out_csv, "r") as out_csv_file:
FileNotFoundError: [Errno 2] No such file or directory: 'out.csv'

neboat commented 2 years ago

I think the output of Cilkscale indicates an error in the Getting Started instructions. On the first line, where the instructions say:

$ python3 /opt/opencilk/share/Cilkscale_vis/cilkscale.py -c qsort -b qsort-bench --args 10000000

the instructions should probably be:

$ python3 /opt/opencilk/share/Cilkscale_vis/cilkscale.py -c ./qsort -b ./qsort-bench --args 10000000

(Note the ./ in front of qsort and qsort-bench in the arguments to cilkscale.py.)

That being said, we should fix the error handling in cilkscale.py in the event that the program failed to run and, therefore, no out.csv file was generated.

As a note, the matplotlib comment is a warning. The Cilkscale visualization and benchmarking tool will still benchmark the program and collect the results into a CSV. It just won't generate a plot. The nonfatal warning is there so that the tool is still useful on systems where the user can't easily install matplotlib themselves.

behoppe commented 2 years ago

Thanks @neboat, I can confirm that the Cilkscale instructions work with

python3 ../share/Cilkscale_vis/cilkscale.py -c ./qsort -b ./qsort-bench --args 10000000

And FWIW I think the instructions would be easier if they said something like

We assume you have installed OpenCilk using the defaults, and that you are in the folder where OpenCilk was installed. For example
cd /opt/opencilk/
sh OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04.sh
... (stuff) ...
cd OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04
before it tells you to
git clone https://github.com/OpenCilk/tutorial
cd tutorial
So then the instructions that I used (above) would work for anyone who installed with defaults and followed Getting started instructions.

dcurtisatmit commented 2 years ago

It seems odd to me that we run fib twice with different numbers of processors and do not show any timing information... i.e., the user should expect to see the running time change. (possibly including some caveats why it wouldn't change?) And if we are showing timing information (which the Intel CilkPlus Guide does), probably we should show some information about the platform? (which the Intel CilkPlus Guide does not)
The tutorial lacks the "Copy" icon on the right side.
when I run sh OpenCilk....sh --help I see the Usage: message but I don't see what the default is wrt include-subdir and exclude-subdir

Usage: OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04.sh [options] Options: [defaults in brackets after descriptions] --help print this message --version print cmake installer version --prefix=dir directory in which to install --include-subdir include the OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04 subdirectory --exclude-subdir exclude the OpenCilk-2.0.0-x86_64-Linux-Ubuntu-20.04 subdirectory --skip-license accept license

Probably there needs to be a note that the number of races detected may vary?
I omitted commenting on the necessity for a full-path-name for qsort and qsort-bench... as this is mentioned above.
The last few changes were to remove the random bolding in the issue: I removed the bolding by using a numbered list. Not totally intuitive, IMHO.

OpenCilk / www.opencilk.org

/doc/users-guide/getting-started/ #59

The tutorial lacks the "Copy" icon on the right side.

Probably there needs to be a note that the number of races detected may vary?

I omitted commenting on the necessity for a full-path-name for qsort and qsort-bench... as this is mentioned above.