Is there a place for newcomers where they can go to browse Ada standard library documentation with links to implementation? In particular, I have trouble finding any info online about the algorithms/numerics libraries.
I found this: gcc/gcc/ada/libgnat at master · gcc-mirror/gcc · GitHub
but the way file the files are named suggests that this is not supposed to be browsed and anyway, it’s only the implementation so not something that can be read as quick reference and documentation by beginners like me. The problem is that my eyes are not accustomed to Ada so even if I have the code, there is a lot of stuff in the code that shouldn’t concern me, yet here I am so I’m clearly looking in the wrong place.
So is there a place that can be looked up conveniently when I want to check for facilities like iota, accumulate, filter, reduce, map and so on?
Just as a note, the implementation will always vary with the compiler vendor. So to find a specific implementation you need to reference the vendors source code or docs.
In the Ada Programming wikibook, you have a page for each standard library unit, each one with, as a minimum, the specification, link to the reference manual, and links to two different open-source implementations. There are even cases where someone has contributed some explanations and examples!
That’s a side effect of a past era in which filenames were limited to 8 characters, but those are indeed the implementations. A simpler way to inspect a particular body is, if you’re using GNAT Studio, to use the Help → GNAT Runtime menu that will take you to the spec you want, and then right-clicking anywhere choose Jump to implementation file.
Or, in any file you’re editing, Ctrl+click the name of the package you want to visit.
I know it isn’t beginner friendly but if you ever need to find a specific package file name you can use the gnat krunch command with the length set to 8. You just supply the .ads to the command. As an example:
$ gnatkr Ada.Containers.Bounded_Vectors.ads 8
a-cobove.ads
It’s basically a GNAT thing (The Ada standard doesn’t dictate how a compiler names its standard library files).
Back when I was writing a zero footprint runtime, I thought I would be all awesome and use more descriptive names like ada-containers-bounded_vectors.ads. It compiled fine UNTIL I had to link to it in an application, then it couldn’t find the file. Krunching the name made everything work. So GNAT forced me to use the awful krunched names in my runtime. Made me sad.
I threw together this Python script a while ago to create symlinks to all of the gnat packages with usable filenames. It’s not very robust, but it works for me.
Thanks everyone. It’s nice that Ada standard has the interface description of the standard libary. I wish it was a bit easier to search for what you want though.
Oh well, relics of the past, I suppose.
Yeah depending on how you are used to searching, it can be varying levels of difficulty for sure.
If it helps, there’s a couple different formats:
HTML, PDF, and TXT
For the TXT format I often fire up vscode and open the folder the files are in and search the whole RM at once.
Additionally if it is something I am partially familiar with, I tend to just go to the HTML version of the Table of Contents or the Index file and do a search there (using control F in my browser). Everything there has links to the specific page something is listed on.
For the PDF version I just search using the PDF.
I think the bigger issue for me isn’t the search difficulty, but just trying to map out terms I am used to from other language to the terms used in Ada (Tagged types vs class types for example). So if it is something I am not familiar with I start with a Google search like “Ada programming XXXXX” and see what terms pop up in the descriptions. Then I search the table of contents and index of the RM for those terms to see what hits I get.
The one nice thing about the RM that I don’t think a lot of new folks notice is that the end of the RM has a lot of “lists” of things to help find stuff that is related but maybe you are unsure which thing you need. Like a list of all the language defined attributes (the names following the apostrophe like Something’Image) for example.