birb/birb

Add README.md

6 months ago, Gary Kramlich
5b565cff55d5
Parents ad245fdd9056
Children 50a501129d04
Add README.md

Testing Done:
Ran codespell

Reviewed at https://reviews.imfreedom.org/r/2879/
1 files changed, 70 insertions(+), 0 deletions(-)
  • +70 -0
    README.md
    • --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/README.md Sat Dec 16 23:31:25 2023 -0600
    @@ -0,0 +1,70 @@
    +# Birb
    +
    +A library of utilities for GLib based applications.
    +
    +## History
    +
    +With the development of Pidgin 3 we've been trying to modularize and create
    +libraries that others are able to use as well. That also means that we didn't
    +have an easy way to reuse things between libraries.
    +
    +We could make the libraries depend on each other, but that doesn't work in the
    +case where we would implement it in libpurple as those dependencies are needed
    +in libpurple or Pidgin and thus we have a circular dependency. Not only that,
    +but pulling in libpurple for a single class/API/whatever would bring in a lot
    +of unnecessary stuff.
    +
    +So to simplify this dependency issue we decided to create yet another library
    +that would just have these pieces that we wanted to reuse. For example,
    +birb has adopted PurpleQueuedOutputStream which is a GOutputStream subclass
    +that manages a queue of output so you can't write as often as you like.
    +
    +This was something we wanted to use in our new external XMPP library
    +[Xeme](https://keep.imfreed.org/xeme/xeme) that is the basis for our new
    +implementation in libpurple. Since it wouldn't make sense to have an external
    +library depend on libpurple for PurpleQueuedOutputStream we pulled it out and
    +put it here in Birb where it can be used much more easily.
    +
    +## Plans
    +
    +As previously mentioned we've already pulled in PurpleQueuedOutputStream as
    +BirbQueuedOutputStream but we do have more than just this planned.
    +
    +There are a few things we want/need to build that need a verb based command
    +line parser. While you can technically do this with
    +[GOptionContext](https://docs.gtk.org/glib/struct.OptionContext.html), there's
    +a number of things you'd have to do to make that happen. Since we need this in
    +multiple libraries, we plan on implementing it here in Birb.
    +
    +It would also be useful to us if we could parse a GMenu in GtkBuilder XML
    +format into a GMenu without using GtkBuilder due to the core/ui split nature of
    +libpurple. As such we would like to implement that here as well.
    +
    +We're also looking at creating an object that can be used to populate a GMenu
    +via signals that would also gather GActionGroup's and their prefixes.
    +
    +Last but not least, we need a simple implementation of StringPrep and precis
    +for a number of things. So we'd like to add at least a basic parser in here
    +to eliminate duplication across the libraries.
    +
    +## Building
    +
    +Birb uses [meson](https://mesonbuild.com/) as a build system. So the steps to
    +build are the same as any other project using meson:
    +
    +```
    +meson setup build
    +meson compile -C build
    +meson test --verbose -C build
    +```
    +
    +## Contributing
    +
    +If you would like to contribute, please see our
    +[Contributing Guide](https://docs.imfreedom.org/contributors-guide/).
    +
    +## API Reference
    +
    +The full API reference can be found at
    +[docs.imfreedom.org/birb/](https://docs.imfreedom.org/birb/)
    +