Wrap naming policy

[koponomarenko]

The wrap tool and the WrapDB system are very powerful features in Meson build system. They make developers life a lot easier by providing an easy and convenient way of using other libs as dependencies in your project.

When using the wrap tool and the WrapDB system to find a particular library I would expect a person to search by the exact name as upstream uses/promotes. E.g.:

$ meson wrap search catch2

There are already two cases on the WrapDB with misleading names right now:

• https://wrapdb.mesonbuild.com/json
• https://wrapdb.mesonbuild.com/catch

json

Upstream: https://github.com/nlohmann/json

This one has nlohmann_json as the official name of the lib (though the repository is simply called "json").

catch

Upstream: https://github.com/catchorg/Catch2

This one has changed its name to catch2 (more about its name change is here).

What should be done in case if upstream changes name?
I would expect for the older version to remain under the old name on the WrapDB. And the new version to have the new corresponding name. This way it is logical and easy to find the exact lib you are looking for. It simply saves you time.

What is the policy for naming a lib on the WrapDB system?
This is already described here. I would just add that in case of the above two projects they don't have a pkg-config file, so I think that the name they use/promote should be used, lowercase only (Catch2 -> catch2).

Name convention for a variable which keeps a value returned by declare_dependency() function
https://mesonbuild.com/Subprojects.html It may be already in use, but I just don't remember seeing it written anywhere.
For ease of use as a subproject, I would suggest that each project has this convention for declaring dependencies - _dep, e.g. for catch2 it would be catch2_dep. Then one can just use it without even looking inside build definitions of that subproject.

PS:
I think that simple but defined rules make our life easier and more predictable, so we can count on them, like in this case with naming.

Please correct me if I am missing anything.

[sarum9in]

I was the one making decision about Catch2 and that's what I used:

    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/catch.pc.in ${CMAKE_CURRENT_BINARY_DIR}/catch.pc @ONLY)
    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/catch.pc DESTINATION ${PKGCONFIG_INSTALL_DIR})

This was later changed in https://github.com/catchorg/Catch2/commit/44722f9ed3d019bdff92d003f9e73333e68c503a

Regarding json name I don't have much context, that could be an oversight, maybe there is some rational I miss. I wasn't part of Meson team when the project was added.

We indeed currently don't have a rename policy. The problem with renames is that it is easy to confuse users if we have 2 or more similar names in wrapdb. I agree that there is a problem, we just need to keep in mind that simply adding a new project and stopping maintaining the old name is not the right choice, at least that's not enough. We should have some way to indicate that there was an old name. Maybe we should have renames as a feature, like marking the old one deprecated and showing it in the list. We also have to be extra careful reusing the old name.

As for the naming policy,

I would just add that in case of the above two projects they don't have a pkg-config file, so I think that the name they use/promote should be used, lowercase only (Catch2 -> catch2).

Pull requests are welcome. Since it's your proposal I will leave it to you to make the change, if you don't have time I can try to improve the documentation article you referenced myself.

_dep, e.g. for catch2 it would be catch2_dep

Since the decision was made to name the project catch the dep name was chosen to be catch_dep as well. There is an inconsistency as we noticed above, but on a different level. You should take a look on a more interesting example though, gtest, there are multiple dependencies declared. And there is no way we can apply a naming convention. We use common sense and a review. If mistake happens we can fix it in a future version or revision, just open a pull request. Since old versions of wrap will not disappear this is a compatible change, user will have to change code anyway to update the wrap files when they upgrade, but they don't need to do anything if they don't.

[jpakkane]

The json one was probably named by me. In hindsight it was perhaps not the best of decisions because "json" is a word used by so many different projects. In the future we should keep a better eye out on the naming.

For this particular case we could do something like the following if the need to rename comes up:

• create a new repo with the new name
• update existing wraps to use the new name
• add a new commit to the json repo telling people that they should start using the new name but keep all other functionality intact
• freeze the json repo and never add anything to it again, but keep the old ones working

As an extra usability feature we could print some sort of "this project is frozen, use new_name instead" message on the wrapdb web page so people can immediately download the correct one.

[koponomarenko]

Pull requests are welcome. Since it's your proposal I will leave it to you to make the change,

Sure. I am happy to help.

You should take a look on a more interesting example though, gtest

Agree, this one is a good example indeed. Even in this case there is naming logic gtest_dep and gmock_dep are pretty obvious names here. But there are also gtest_main_dep and gmock_main_dep for a special case, so yes not much to standardize here ... .

• create a new repo with the new name

We actually need two here: nlohmann_json and catch2. Could any of you guys create them as I don't have rights? Though I will be happy to help with content for them.

• update existing wraps to use the new name

I can help with that.

• add a new commit to the json repo telling people that they should start using the new name

I am not sure I understand how this works? How it will tell people that info?

[sarum9in]

I am not sure I understand how this works? How it will tell people that info?

We need a separate feature in mesonwrap/core meson to support deprecation. The way I see it now is to mark a repository deprecated in master branch and export it somehow through mesonwrap API. Then show a warning in WebUI/core meson wrap code itself. It is a separate thing to do though.

We will probably have to reserve names forever though to keep old wraps alive. Until (if) we develop a retention policy. Let's track deprecation separately.

[jpakkane]

I am not sure I understand how this works? How it will tell people that info?

Simply having message('WARNING: this wrap is deprecated, you might want to use nlohmann_json instead.') in the build file should fix most issues.

[sarum9in]

It will not surface though until the user will try to configure the project, after downloading the wrap. I think we should aim for notification in the list, e.g.

$ meson wrap list
...
catch [deprecated, use catch2]
catch2
cereal
...

[jpakkane]

We can do both.

[koponomarenko]

A new name of a lib doesn't necessarily mean depreciation of the old one. Somebody may decide to continue to support it.

Taking that into account I wouldn't mark a lib as "depricated" in Meson. Instead I would suggest to leave it to the upstream and developers who use this lib to check the current developmen state of the lib.

Looks like handling a wrongly named wrap case is tricky.

• add a new commit to the json repo telling people that they should start using the new name but keep all other functionality intact
• freeze the json repo and never add anything to it again, but keep the old ones working

The downside of this approach is that this particular name cannot be used anymore by any other wrap. Are we ok with this?

Maybe there should be a policy to release this names after some time?

[sarum9in]

For now I just marked both deprecated in github repo description, I will think about functionality how to handle it better.

A new name of a lib doesn't necessarily mean depreciation of the old one. Somebody may decide to continue to support it.

Do you mean cases like Gnome_2 and Gnome_3 (not literally): 2 major versions competing? Otherwise it sounds confusing.

Retention policy.

I have a different idea. Let's think about retention policy outside of renaming scope. When does it make sense to drop the name? My idea is when it has no valid versions. When is it fine to drop a version? When there is no upstream release source code hosted by author. We will definitely not commit to hosting source code, only wraps. So if they drop let's say catch-2.2.1 we can safely remove the version, that's my take on this.

[koponomarenko]

I would like to let you know that I updated Subprojects page with naming convention and Adding new projects to WrapDB page with more detailed steps on how one can contribute a wrap file.

Do you mean cases like Gnome_2 and Gnome_3 (not literally): 2 major versions competing? Otherwise it sounds confusing.

Yes, that is a good example.

I have a different idea. Let's think about retention policy outside of renaming scope.

Should we create another issue to discuss it there and close this one?