[Stk] Improving the directory structure

Wed Jan 15 17:05:36 PST 2014

I understand your approach.

There seems to be an agreement to separate the utilities and system-dependent classes. What do you think of the following arrangement: 

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

Cheers

Ariel

On 12 Jan 2014, at 19:52, Tristan Matthews <le.businessman at gmail.com> wrote:

> 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
> _______________________________________________
> Stk mailing list
> Stk at ccrma.stanford.edu
> http://ccrma-mail.stanford.edu/mailman/listinfo/stk

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://ccrma-mail.stanford.edu/pipermail/stk/attachments/20140116/7cb2a7ac/attachment.html 