[Stk] Improving the directory structure

Sun Jan 12 11:52:47 PST 2014

On Sun, Jan 12, 2014 at 1:41 PM, Perry Cook <prc at cs.princeton.edu> wrote:

> My 2 cents.  I totally agree with Gary.
>
> If I need only a few classes, I copy those into a new project directory
> and either make a new Makefile, or hack a copy of the existing one to
> remove what I don't need.
>
> The primary purpose of STK has always been pedagogical, to show all that
> can be done with parametric synthesis, thus building everything and running
> the Demo should be the default use-case.  Power users and developers should
> be able to figure it out from having .cpp in source and .h in include.
>
> Separating out odd utilities (makesine) and system-dependent things does
> make sense.
>

Agreed, especially when it comes to adding support for more platforms.
However, I think "separating out" in a useful way has a lot more to do with
the actual build system and implementation than the directory structure.

Best,
Tristan

> On Jan 12, 2014, at 8:31 AM, Gary Scavone <gary at ccrma.Stanford.EDU> wrote:
>
> > Hi Ariel,
> >
> > Thanks for the recent bug fixes submitted to the github repository!
> >
> > I've commented a bit on this proposal in the past.  I'll again mention
> that one of my highest priorities is cross-platform support.  Any changes
> that are made should help maintain or improve that situation.
> >
> > I've thought a lot about the organization of the classes over the years.
>  As we are working with C++, I consider this structuring primarily through
> class inheritance (which is readily visualizable: see
> https://ccrma.stanford.edu/software/stk/classstk_1_1Stk.html).  I made
> various changes to try to improve the clarity of the structure, with
> abstract base classes such as Filter, Generator, …
> >
> > There are many different ways to use the STK distribution.  Some people
> like to build a library and simply link to that.  Others like to hand-pick
> the classes they need for a given project.  Personally, I do both.
> >
> > Now, regarding the proposal to move the various classes into different
> subdirectories, I see some significant disadvantages and I don't
> necessarily see any advantages.  On the negative side:
> >
> > 1. It would make it hard to find and edit classes if they are in
> different directories.  If I want to copy only a few classes into a given
> project, it is easier to only have to look for them in the src/ and
> include/ directories than in a bunch of subdirectories.  I often need to
> make global edits or searches of all the header files (for example, to
> change the dates) … this would be more difficult.
> >
> > 2. It would require a variety of changes in Makefiles to allow the
> library and projects to be compiled.
> >
> > 3. There would likely be many cases where classes in subdirectories need
> to include classes from other directories … this not only presents
> potential problems for compiling but it doesn't help the user understand
> the overall inheritance of the classes.  For example, why should the Filter
> abstract base class be separated from the other Filter subclasses?
> >
> > What are the positives?  I think the class hierarchy is where
> "organization" should happen, not using directories.
> >
> > But as I've said in the past, it might be useful to put all classes that
> have system dependencies into a separate directory (classes such as
> RtAudio, RtMidi, the Socket classes, Threading, …).  That would make it
> clearer to the user which classes are purely system-independent and which
> have some dependencies.  The one catch in that idea is that the Stk
> (super)class itself has a bit of system-dependent code in it!
> >
> > Finally, I'm tending to view STK more and more as a library, simply
> because it is easier to maintain that way.  As such, the current directory
> structure seems to follow standard practices in the coding community.
> >
> > These are my opinions.  If others have ideas and substantiations, I'm
> willing to listen.
> >
> > Regards,
> >
> > --gary
> >
> > On 2014-01-12, at 12:03 AM, Ariel Elkin <arielelkin at gmail.com> wrote:
> >
> >> Hi guys,
> >>
> >> Now that the STK's GitHub repository is established, I'd like to offer
> some motivations for improving the STK's directory structure.
> >>
> >> One of my favourite features of the STK is its modularity. There's a
> clear loose coupling pattern; synths and filters, for instance, nicely
> encapsulate their functionality. Functionality across the source files is
> widely (and wisely) distributed.
> >>
> >> Yet its directory structure, doesn't really reflect that.
> >>
> >> Currenltly, ALL the source files are in src/, and ALL the header files
> are in include/. This suggests the STK is a monolithic library, but that's
> not really the case…
> >>
> >> Most use cases of STK involve a handful of its classes, the user
> cherry-picks them before compile time. We very rarely need every one of the
> 104 classes in our project.
> >>
> >> If I want to use, say, PRCRev, the only classes I need to include are
> the ones it inherits from:
> >> PRCRev
> >> Effect
> >> Delay
> >> Filter
> >> and Stk
> >>
> >> that's 5 classes out of 104
> >>
> >> Another example: if I want to use, say, Wurley, I only need 12 classes.
> Out of the 104 classes.
> >>
> >> It makes sense for frameworks like Pure Data or SuperCollider to build
> every source file, given that the user may use of any one of its
> constituent classes at runtime. But the STK is for programmers, and
> programmers make decisions, before compile time, about which classes will
> and will not be used .
> >>
> >> The STK's directory structure needs to facilitate that. We should make
> it easier for a STK user to cherry-pick the classes he or she will actually
> use. Additionally, this would give users a much clearer picture of how the
> library is really structured.
> >>
> >> I'd say a good directory structure reflects the loose coupling pattern
> in place, grouping classes by functionality. I propose the following:
> >>
> >>
> >> _base/
> >> Abstract base classes (e.g. Effect, Delay, Filter)
> >>
> >> _filters/
> >> All the classes that filter/effect audio (e.g. TwoPole, PRCVerb, etc.)
> >>
> >> _synths/
> >> All the classes that generate audio (e.g. Guitar, Mandolin, Twang, etc.)
> >>
> >> _rawwaves/
> >> All the raw wave files
> >>
> >>
> >> audio_layer/
> >> RtAudio
> >> RtAudio
> >> RtError
> >> as well as the contents of src/include/:
> >> asio, dsound, soundcard, etc.
> >>
> >> File_IO/
> >> FileRead
> >> FileLoop
> >> FileWrite
> >> WvIn
> >> WvOut
> >> FileWvIn
> >> FileWvOut
> >>
> >> System_IO/
> >> RtWvIn
> >> RtWvOut
> >> RtWvIn
> >>
> >> Multithreading/
> >> All the multithreading classes:
> >> Thread
> >> Mutex
> >>
> >> Networking/
> >> All the networking classes:
> >> UdpSocket
> >> Socket
> >> TcpClient
> >> TcpServer
> >>
> >> MIDI/
> >> MidiFileIn
> >> RtMidi
> >> makemidi.c
> >>
> >> Misc/
> >> makefun.c
> >> makewavs.c
> >> sine.c
> >>
> >>
> >> This proposal for a new directory structure is, of course, open to
> amendments, additions, and fixes.
> >>
> >> So, these are the motivations for reorganising the directory structure,
> and I hope I've suggested a clean way in which it can be done.
> >>
> >> Looking forward to your thoughts.
> >>
> >> Cheers
> >>
> >> Ariel
> >>
> >>
> >> _______________________________________________
> >> Stk mailing list
> >> Stk at ccrma.stanford.edu
> >> http://ccrma-mail.stanford.edu/mailman/listinfo/stk
> >
> >
> > _______________________________________________
> > Stk mailing list
> > Stk at ccrma.stanford.edu
> > http://ccrma-mail.stanford.edu/mailman/listinfo/stk
>
> _______________________________________________
> Stk mailing list
> Stk at ccrma.stanford.edu
> http://ccrma-mail.stanford.edu/mailman/listinfo/stk
>

-- 
Tristan Matthews
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://ccrma-mail.stanford.edu/pipermail/stk/attachments/20140112/91aea324/attachment.html 