Thread overview
Specifying possible version statements for libraries and apps
October 08

I would like to suggest adding some kind of standard metadata format to declare which custom versions (maybe also debug versions?) an application or library consumes and defines. This could be used as documentation for others, to know what kind of versions exist and may be used for example for auto completion and static analysis to see if typos in versions have been made.

I was thinking about this because issues like this could be avoided: https://github.com/das-developers/das2D/issues/2 (all builtin versions would be included in the list by default, could lint the list for not clashing the builtin versions)

I'm thinking about a few different ways how this could be realized:

  1. having version = X; or // version = X; in the head of D files.
    Advantage: This would be the most easy one to adapt as some projects maybe already use some kind of structure like this. Could work out of the box for some projects already. Can easily add documentation in the form of comments.
    Disadvantage: in a long block of versions you could introduce typos when duplicating them in conditional blocks.

  2. have it integrated in dub.json/dub.sdl like "availableVersions": ["A", "B", "C"]
    Advantage: no extra file needed for DUB projects, making for a clean project. Can be inherited / shown easily and parsing can trivially be extended. Having them defined exactly once can prevent typos with full certainty.
    Disadvantage: Needs to be added into all projects, no documentation in JSON format possible. (or more verbose format needed, but writing long text in JSON strings is not fun once quotes and new lines are introduced) Not applicable to non-DUB projects.

  3. have a dedicated .ddoc/.txt/.sdl/.json/.whatever file to list versions and documentation.
    Advantage: Works universally in projects, can for example be included in the IDE's own project format. Having them defined exactly once can prevent typos with full certainty.
    Disadvantage: Needs to be added into all projects. Not being bound to any build system means it's unclear where versions go and how dependencies/dependants work.

Which ones of those would you prefer and do you think this is a good idea in general?

Once settled on a format it would be relatively easy to add suggestions and linter errors for it to editors and LSP clients or make a dedicated tool for it.

October 08
what i was tempted to do in the adrdox was pull out the version(X) blocks automatically
so it knows which ones are used. then filter the built-in ones. this should leave just the custom ones
then in the ddoc module header, do like

Version_Identifiers:
   embedded_httpd = whatever
   scgi = whatever

(or Debug_Identifiers:)


and it formats that into a table, same as it does for function parameters
then the generated page can also include ones it auto-detected but did not have a section as an "undocumented in source" generation, which both acts as a warning to the author that it needs a doc, and as a hint to the user that there might be something there
October 08

On Friday, 8 October 2021 at 17:01:47 UTC, WebFreak001 wrote:

>

I was thinking about this because issues like this could be avoided: https://github.com/das-developers/das2D/issues/2 (all builtin versions would be included in the list by default, could lint the list for not clashing the builtin versions)

Thanks for noticing that bug, and more importantly, filing an issue :-)

So until you pointed it out I didn't realize I was operating under the assumption that the pre-defined version strings were the only values understood by version, even though the top of the linked documentation page clearly states that, like a C macro, any version identifier string is acceptable.

I'm not sure how this could be addressed without introducing more restrictions then it's worth. If I mistype the "_WIN32" macro in a C source file there's no way for the compiler to know what I meant, so I just accept that and move on.

This one is definitely more insidious though, since there's so few big-endian machines around for testing anymore.

Out of curiosity, what was the last version of dmd to even run on Solaris?

October 09

On Friday, 8 October 2021 at 17:01:47 UTC, WebFreak001 wrote:

>

I would like to suggest adding some kind of standard metadata format to declare which custom versions (maybe also debug versions?) an application or library consumes and defines. This could be used as documentation for others, to know what kind of versions exist and may be used for example for auto completion and static analysis to see if typos in versions have been made.

I think 1 is a good idea, as it fits existing code already. I feel like it's better not to do it for debug identifiers, as they tend to be private to a project, unlike version identifiers.