Please bump library SONAME (SOVERSION) from 0 to 1

[hosiet]

There is some ABI breaks between marisa-trie v0.2.x and v0.3.x. For example, in c8cd0af :

   void build(Keyset &keyset, int config_flags = 0);
 
-  void mmap(const char *filename);
+  void mmap(const char *filename, int flags = 0);
   void map(const void *ptr, std::size_t size);

...and there are more of them, such as marisa::grimoire::io::Mapper::open(char const*, int)@Base, marisa::grimoire::io::Mapper::open_(char const*, int)@Base, etc.

With my Debian Developer hat and the maintainer role as listed on https://tracker.debian.org/pkg/marisa on, Could you please bump the SOVERSION in CMakeLists.txt from ${Marisa_VERSION_MAJOR} (aka 0) to a higher value (e.g., 1)? This will be needed for a proper package maintenance in Debian, Ubuntu and other Linux distributions that ship marisa-trie library. Thanks!

[jmr]

There is some ABI breaks between marisa-trie v0.2.x and v0.3.x. For example, in c8cd0af

Could this one be fixed by splitting this into two functions mmap(const char*) and mmap(const char*, int)?

What other breaks did you find?

I think there could be a few options here.

1. increase SOVERSION and accept that it will be out of sync with the major version (or get back in sync by skipping a major version at some point)
2. increase SOVERSION and also call what's currently there 1.0 as suggested elsewhere by @glebm (Although I would like to make more breaking changes)
3. Rename libmarisa to libmarisa-0 until we reach version 1
4. Make the reset of the world agree with SemVer in that version 0 provides no guarantees. Not going to happen any time soon.

[hosiet]

For full symbol changes between v0.2.6 and git HEAD:

-> % diff -u debian/libmarisa0.symbols debian/libmarisa1.symbols 
--- debian/libmarisa0.symbols   2025-09-22 10:22:58.867542193 -0400
+++ debian/libmarisa1.symbols   2025-09-22 10:23:09.799645694 -0400
@@ -1,16 +1,19 @@
-libmarisa.so.0 libmarisa0 #MINVER#
+libmarisa.so.1 libmarisa1 #MINVER#
 * Build-Depends-Package: libmarisa-dev
  (subst)_ZN6marisa4Trie3mapEPKv{size_t}@Base
  _ZN6marisa4Trie4loadEPKc@Base
- _ZN6marisa4Trie4mmapEPKc@Base
+ _ZN6marisa4Trie4mmapEPKci@Base
  _ZN6marisa4Trie4readEi@Base
  _ZN6marisa4Trie4swapERS0_@Base
  _ZN6marisa4Trie5buildERNS_6KeysetEi@Base
  _ZN6marisa4Trie5clearEv@Base
+ _ZN6marisa4TrieC1EOS0_@Base
  _ZN6marisa4TrieC1Ev@Base
+ _ZN6marisa4TrieC2EOS0_@Base
  _ZN6marisa4TrieC2Ev@Base
  _ZN6marisa4TrieD1Ev@Base
  _ZN6marisa4TrieD2Ev@Base
+ _ZN6marisa4TrieaSEOS0_@Base
  _ZN6marisa4readERSiPNS_4TrieE@Base
  _ZN6marisa5Agent10init_stateEv@Base
  _ZN6marisa5Agent4swapERS0_@Base
@@ -18,10 +21,16 @@
  _ZN6marisa5Agent9set_queryEPKc@Base
  (subst)_ZN6marisa5Agent9set_queryEPKc{size_t}@Base
  (subst)_ZN6marisa5Agent9set_queryE{size_t}@Base
+ _ZN6marisa5AgentC1EOS0_@Base
+ _ZN6marisa5AgentC1ERKS0_@Base
  _ZN6marisa5AgentC1Ev@Base
+ _ZN6marisa5AgentC2EOS0_@Base
+ _ZN6marisa5AgentC2ERKS0_@Base
  _ZN6marisa5AgentC2Ev@Base
  _ZN6marisa5AgentD1Ev@Base
  _ZN6marisa5AgentD2Ev@Base
+ _ZN6marisa5AgentaSEOS0_@Base
+ _ZN6marisa5AgentaSERKS0_@Base
  _ZN6marisa5freadEP8_IO_FILEPNS_4TrieE@Base
  _ZN6marisa5writeERSoRKNS_4TrieE@Base
  _ZN6marisa6Keyset16append_key_blockEv@Base
@@ -38,12 +47,12 @@
  _ZN6marisa6KeysetC1Ev@Base
  _ZN6marisa6KeysetC2Ev@Base
  _ZN6marisa6fwriteEP8_IO_FILERKNS_4TrieE@Base
- _ZN6marisa8grimoire2io6Mapper4openEPKc@Base
+ _ZN6marisa8grimoire2io6Mapper4openEPKci@Base
  (subst)_ZN6marisa8grimoire2io6Mapper4openEPKv{size_t}@Base
  (subst)_ZN6marisa8grimoire2io6Mapper4seekE{size_t}@Base
  _ZN6marisa8grimoire2io6Mapper4swapERS2_@Base
  _ZN6marisa8grimoire2io6Mapper5clearEv@Base
- _ZN6marisa8grimoire2io6Mapper5open_EPKc@Base
+ _ZN6marisa8grimoire2io6Mapper5open_EPKci@Base
  (subst)_ZN6marisa8grimoire2io6Mapper5open_EPKv{size_t}@Base
  (subst)_ZN6marisa8grimoire2io6Mapper8map_dataE{size_t}@Base
  _ZN6marisa8grimoire2io6MapperC1Ev@Base
@@ -86,10 +95,10 @@
  _ZN6marisa8grimoire4trie4Tail4map_ERNS0_2io6MapperE@Base
  _ZN6marisa8grimoire4trie4Tail4readERNS0_2io6ReaderE@Base
  _ZN6marisa8grimoire4trie4Tail4swapERS2_@Base
- _ZN6marisa8grimoire4trie4Tail5buildERNS0_6vector6VectorINS1_5EntryEEEPNS4_IjEE17marisa_tail_mode_@Base
+ _ZN6marisa8grimoire4trie4Tail5buildERNS0_6vector6VectorINS1_5EntryEEEPNS4_IjEE16marisa_tail_mode@Base
  _ZN6marisa8grimoire4trie4Tail5clearEv@Base
  _ZN6marisa8grimoire4trie4Tail5read_ERNS0_2io6ReaderE@Base
- _ZN6marisa8grimoire4trie4Tail6build_ERNS0_6vector6VectorINS1_5EntryEEEPNS4_IjEE17marisa_tail_mode_@Base
+ _ZN6marisa8grimoire4trie4Tail6build_ERNS0_6vector6VectorINS1_5EntryEEEPNS4_IjEE16marisa_tail_mode@Base
  _ZN6marisa8grimoire4trie4TailC1Ev@Base
  _ZN6marisa8grimoire4trie4TailC2Ev@Base
  _ZN6marisa8grimoire4trie9LoudsTrie10fill_cacheEv@Base
@@ -150,6 +159,4 @@
  (subst)_ZNK6marisa8grimoire6vector9BitVector5rank1E{size_t}@Base
  (subst)_ZNK6marisa8grimoire6vector9BitVector7select0E{size_t}@Base
  (subst)_ZNK6marisa8grimoire6vector9BitVector7select1E{size_t}@Base
- _ZTIN6marisa9ExceptionE@Base
- _ZTSN6marisa9ExceptionE@Base
  _ZZN6marisa8grimoire4trie6Header10get_headerEvE3buf@Base

To be more specific:

• c8cd0af#diff-ce798d9cda720e4e05344949dedeb8f231d6aa391ae218c1c3e9ff3abeff1411

   Mapper();
   ~Mapper();
 
-  void open(const char *filename);
+  void open(const char *filename, int flags = 0);
   void open(const void *ptr, std::size_t size);
 
   template <typename T>

   int fd_;
 #endif  // (defined _WIN32) || (defined _WIN64)
 
-  void open_(const char *filename);
+  void open_(const char *filename, int flags);
   void open_(const void *ptr, std::size_t size);
 
   const void *map_data(std::size_t size);

• 3c0e57e#diff-effb5bbb8e4cd7cd9dfd35f07f3f7a852763620b9fe26056b391e7f0de0d31d3L19-L50

 // This library provides 2 kinds of TAIL implementations.
-typedef enum marisa_tail_mode_ {
+enum marisa_tail_mode {
   // MARISA_TEXT_TAIL merges last labels as zero-terminated strings. So, it is
   // available if and only if the last labels do not contain a NULL character.
   // If MARISA_TEXT_TAIL is specified and a NULL character exists in the last
@@ -134,11 +118,11 @@ typedef enum marisa_tail_mode_ {
   MARISA_BINARY_TAIL = 0x02000,
 
   MARISA_DEFAULT_TAIL = MARISA_TEXT_TAIL,
-} marisa_tail_mode;
+};

...which triggers the following symbol difference:

- marisa::grimoire::trie::Tail::build(marisa::grimoire::vector::Vector<marisa::grimoire::trie::Entry>&, marisa::grimoire::vector::Vector<unsigned int>*, marisa_tail_mode_)@Base
+ marisa::grimoire::trie::Tail::build(marisa::grimoire::vector::Vector<marisa::grimoire::trie::Entry>&, marisa::grimoire::vector::Vector<unsigned int>*, marisa_tail_mode)@Base
  marisa::grimoire::trie::Tail::clear()@Base
  marisa::grimoire::trie::Tail::read_(marisa::grimoire::io::Reader&)@Base
- marisa::grimoire::trie::Tail::build_(marisa::grimoire::vector::Vector<marisa::grimoire::trie::Entry>&, marisa::grimoire::vector::Vector<unsigned int>*, marisa_tail_mode_)@Base
+ marisa::grimoire::trie::Tail::build_(marisa::grimoire::vector::Vector<marisa::grimoire::trie::Entry>&, marisa::grimoire::vector::Vector<unsigned int>*, marisa_tail_mode)@Base

• And finally, 0ecfe31b

The removal of marisa::Exception in favor of std::exception is not an API break, but it is an ABI break.

---

I am fine with either of Option 1, 2, or 3.