search

ValleyBell / libvgm

A more modular rewrite of most components from VGMPlay. will include sub-libraries for audio output, sound emulation and VGM playback
irc://irc.digibase.ca/#vgmrips
136 stars 33 forks source link

Naming discussion #58

Open ValleyBell opened 3 years ago

ValleyBell commented 3 years ago

I'd like to standardize the naming mess we currently have in libvgm.

What we currently have:

So in conclusion we have a mess of where we sometimes use libvgm and sometimes only vgm.

I'd like to standardize and sort this mess. And yes, this will probably be an API break, especially in case of renaming packages/libraries.

My current suggestion would be:

@superctr, @jprjr: Any thoughts?

jprjr commented 3 years ago

For the GCC library names I'd recommend sticking with "libvgm-player.a" etc, and not going to "liblibvgm-player.a".

Off the top of my head I can think of a few libraries that have "lib" in their name (zlib, libcurl) that are just linked with flags like "-lz", "-lcurl", etc. Like, I know if I type "-l(whatever)" the linker will search for "lib(whatever)", in my head I sort-of auto-translate "-l" to the word "lib". Having the file named "liblib" so the flag becomes "-llibvgm" is kind of confusing.

Renaming pkg-config to "libvgm-*" seems like a good idea though, I think that's in line with most naming conventions (using the project's "main" name)

Libcurl, I use "pkg-config libcurl"

Zlib, I use "pkg-config zlib"

So if the main name is libvgm, then "pkg-config libvgm" makes sense.

On November 15, 2020 8:39:00 AM EST, ValleyBell notifications@github.com wrote:

I'd like to standardize the naming mess we currently have in libvgm.

What we currently have:

  • actual library name (= repository name, CMake name, used in descriptions): libvgm

  • include directory name: include/vgm

  • pkg-config package names: vgm-* (e.g. "vgm-emu", "vgm-player", ...)

  • CMake target names: libvgm::vgm-* (e.g. "libvgm::vgm-emu", "libvgm::vgm-player", ...)

  • GCC library names: libvgm-*.a (e.g. "libvgm-emu.a", "libvgm-player.a", ...)
    Those are linked with e.g. -l vgm-emu.

  • MSVC library names: vgm-*.lib (e.g. "vgm-emu_Win32.lib", "vgm-player_Win32.lib", ...)

So in conclusion we have a mess of where we sometimes use libvgm and sometimes only vgm.

I'd like to standardize and sort this mess. And yes, this will probably be an API break, especially in case of renaming packages/libraries.

My current suggestion would be:

  • library name: libvgm
  • include directory name: include/libvgm (with a few fallback header files in include/vgm to prevent too much breaking)
  • pkg-config package names: libvgm-* (e.g. "libvgm-emu", "libvgm-player", ...)
  • CMake target names: libvgm::* (e.g. "libvgm::emu", "libvgm::player", ...)
  • GCC library names: liblibvgm-*.a (e.g. "liblibvgm-emu.a", "liblibvgm-player.a", ...)
    My goal here is to be able to link against -l libvgm-emu.
  • MSVC library names: libvgm-*.lib (e.g. "libvgm-emu_Win32.lib", "libvgm-player_Win32.lib", ...)

@superctr, @jprjr: Any thoughts?

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/ValleyBell/libvgm/issues/58

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

superctr commented 3 years ago

I agree with jpjr above. Consistency is good, but it should be consistent with the user's expectations rather than the physical file structure.

It should be given that the library .a file should be called libvgm-*.a instead of liblibvgm-*.a, I don't have a single installed library right know that has liblib*. I also read the GCC -l* as -lib*.

When it comes to include filenames, there is however a lack of consistency in my installed libraries. For example, libcurl include files are include/curl, but libmodplug are in include/libmodplug. So I don't really care too much about where those files will go in the future, as long as the existing vgm/* headers are kept for backwards compatibility.

kode54 commented 3 years ago

What about libopenmpt? libmodplug is kind of irrelevant except for legacy distributions that still package it.

jprjr commented 3 years ago

I'd probably just keep the headers under the "vgm" folder.

Having the headers be named "libvgm/player" is a bit redundant. If I'm writing C++ and including headers, the fact that I'm linking against a library is implied, right? Plenty of projects use "lib" prefixes in their project name but drop them from their header file names.

If you do rename it, I wouldn't maintain compatibility headers. That's just one more thing to maintain and doesn't really add a whole lot of value.

On November 17, 2020 8:24:32 PM EST, Christopher Snowhill notifications@github.com wrote:

What about libopenmpt? libmodplug is kind of irrelevant except for legacy distributions that still package it.

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/ValleyBell/libvgm/issues/58#issuecomment-729315536

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

ValleyBell commented 3 years ago

For the GCC library names I'd recommend sticking with "libvgm-player.a" etc, and not going to "liblibvgm-player.a".

Off the top of my head I can think of a few libraries that have "lib" in their name (zlib, libcurl) that are just linked with flags like "-lz", "-lcurl", etc. Like, I know if I type "-l(whatever)" the linker will search for "lib(whatever)", in my head I sort-of auto-translate "-l" to the word "lib". Having the file named "liblib" so the flag becomes "-llibvgm" is kind of confusing.

Okay, this makes total sense. I edited it to remove the "liblib".

I'd probably just keep the headers under the "vgm" folder. Having the headers be named "libvgm/player" is a bit redundant.

The "vgm" folder actually bothers me a lot. Unlike "curl", "vgm" is a lot more generic. You could maybe compare this to libav (ffmpeg). "AV" is a similarly generic term as "VGM". They keep also have their includes in folders like "libavutil" and "libavformat".

I plan to have some basic compatibility headers in the "vgm" folder for a limited time. They will be removed once the "player" part gets its C-API.

superctr commented 3 years ago

The "vgm" folder actually bothers me a lot. Unlike "curl", "vgm" is a lot more generic. You could maybe compare this to libav (ffmpeg). "AV" is a similarly generic term as "VGM". They keep also have their includes in folders like "libavutil" and "libavformat".

Most libraries made by the Xiph group, libao, libogg, libFLAC, libvorbis etc remove the lib prefix from the include folder. Those maybe could be considered a little closer to libvgm since they deal with the file formats (or codecs) directly.

jprjr commented 3 years ago

Yeah, the way I see it, this is the VGM library. You wanna decode VGM, you type #include <vgm/...>.

But no I get what you're saying, it's a library for vgm (the file format) and not VGM (all videogame music).

Plus the one scenario is, let's say you went with just "vgm", then later somebody comes along and decides to re-invent libgme and write an all-encompassing VGM library, so they come up with "VGM-lib" and put their headers under "libvgm" or "vgmlib" or something like that. Then you've definitely got confusion over which headers are for which library.

Whereas if you're under "libvgm", y'know, you can say look, the repo is libvgm, the headers folder is libvgm, it all matches, it's (hopefully) a bit less confusing should a new, similarly-named project pop up.

superctr commented 3 years ago

But no I get what you're saying, it's a library for vgm (the file format) and not VGM (all videogame music).

the latter description actually describes it pretty well actually. Remember that libvgm is split into three components. The sound chip emulation library vgm/emu, the audio driver wrapper vgm/audio and the player vgm/player. Only vgm/player is the "library for the VGM file format", the other two parts are generic components that could be used in any (game music/chiptune related) project.

As I said, I think that we can agree that it would be less painful to simply keep the vgm/* location for installed header files, and the vgm-xxx pkgconfig files. As backwards compatibility will be kept for existing programs that use the library.

But now that I think of it, if we do this renaming (of everything) at the same time, the old version of the library could be kept installed in case we start doing compatibility-breaking changes... I have a few that I'm thinking of now.