Hi All,

I did some brainstorming in a long session with AI and produced a plan
for file-based modules for Csound. I've posted a summary at:

https://github.com/csound/csound/issues/2340

The idea for backwards compatibility is that #include works as-is but
import uses the proposed module-based system, and to encourage users
to adopt import over #include moving forward.

I think for feedback it might be good to carry on on the github issue
rather than on the mailing list here.

Thanks!
steven

Looks good to me, but sounds like hard work.

I think fixing name clashes is a very good idea, in fact something essential really even outside the scope of this module system.

Prof. Victor Lazzarini
Maynooth University
Ireland

> On 31 Oct 2025, at 17:06, Steven Yi  wrote:
>
> *Warning*
>
> This email originated from outside of Maynooth University's Mail System. Do not reply, click links or open attachments unless you recognise the sender and know the content is safe.
>
> Hi All,
>
> I did some brainstorming in a long session with AI and produced a plan
> for file-based modules for Csound. I've posted a summary at:
>
> https://github.com/csound/csound/issues/2340
>
> The idea for backwards compatibility is that #include works as-is but
> import uses the proposed module-based system, and to encourage users
> to adopt import over #include moving forward.
>
> I think for feedback it might be good to carry on on the github issue
> rather than on the mailing list here.
>
> Thanks!
> steven

I think it'll be tricky but worth it.

Just a note, I revised the proposal in the PR to focus on using
Python-style import syntax rather than Javascript. This is mainly
because JS ties in object destructuring syntax into its import system,
which works well but it isn't something that makes sense with Csound
IMO. Python's import syntax is pretty clear to me and I think it would
fit in nicely with Csound orc language. The one thing would be that
we'd have to use a convention for file names (i.e., files must end in
.orc, similar to how python modules have to be files that end in .py
or .pyc).

On Fri, Oct 31, 2025 at 1:48 PM Victor Lazzarini
<000010b17ddd988e-dmarc-request@listserv.heanet.ie> wrote:
>
> Looks good to me, but sounds like hard work.
>
> I think fixing name clashes is a very good idea, in fact something essential really even outside the scope of this module system.
>
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 31 Oct 2025, at 17:06, Steven Yi  wrote:
> >
> > *Warning*
> >
> > This email originated from outside of Maynooth University's Mail System. Do not reply, click links or open attachments unless you recognise the sender and know the content is safe.
> >
> > Hi All,
> >
> > I did some brainstorming in a long session with AI and produced a plan
> > for file-based modules for Csound. I've posted a summary at:
> >
> > https://github.com/csound/csound/issues/2340
> >
> > The idea for backwards compatibility is that #include works as-is but
> > import uses the proposed module-based system, and to encourage users
> > to adopt import over #include moving forward.
> >
> > I think for feedback it might be good to carry on on the github issue
> > rather than on the mailing list here.
> >
> > Thanks!
> > steven

Another note: I'm currently deep in the module system implementation
and am working through some design things that have come up. The idea
of global vars is a little interesting in the context of modules, and
I might be under the influence of Python's design at the moment, but
the idea right now I have is:

1. any var in "instr 0" space is just global, and is "module global"
2. Accessing a global from an instrument traditionally is done by
g-vars. We could have it similar to python where you can access
globals by default without using global, but use global if you need to
write to them:

```
bus1:a init 0
bus2:a init 0

instr Test
  global bus1, bus2
  bus1 += oscili(0.25, 440)
  bus2 += oscili(0.25, 550)
endin
```

3. g-vars become grandfathered in but above becomes best practice
moving forward.

The reason this needs some clarification is for importing and using
vars from a module. For example, you might have:

config.orc:
```
maxNotes:i = 32
```

test.orc:
```
import config

maxalloc(1, config.maxNotes)
```

I think this looks clear and also gets rid of the awkward
`myVar@global:i` syntax.

Thoughts? I'm still looking at other languages and module
implementations to get ideas, but so far this is the leading candidate
in my mind, considering we have to recontextualize what g-vars means
and how they have been used historically.



On Sun, Nov 2, 2025 at 11:50 AM Steven Yi  wrote:
>
> I think it'll be tricky but worth it.
>
> Just a note, I revised the proposal in the PR to focus on using
> Python-style import syntax rather than Javascript. This is mainly
> because JS ties in object destructuring syntax into its import system,
> which works well but it isn't something that makes sense with Csound
> IMO. Python's import syntax is pretty clear to me and I think it would
> fit in nicely with Csound orc language. The one thing would be that
> we'd have to use a convention for file names (i.e., files must end in
> .orc, similar to how python modules have to be files that end in .py
> or .pyc).
>
> On Fri, Oct 31, 2025 at 1:48 PM Victor Lazzarini
> <000010b17ddd988e-dmarc-request@listserv.heanet.ie> wrote:
> >
> > Looks good to me, but sounds like hard work.
> >
> > I think fixing name clashes is a very good idea, in fact something essential really even outside the scope of this module system.
> >
> > Prof. Victor Lazzarini
> > Maynooth University
> > Ireland
> >
> > > On 31 Oct 2025, at 17:06, Steven Yi  wrote:
> > >
> > > *Warning*
> > >
> > > This email originated from outside of Maynooth University's Mail System. Do not reply, click links or open attachments unless you recognise the sender and know the content is safe.
> > >
> > > Hi All,
> > >
> > > I did some brainstorming in a long session with AI and produced a plan
> > > for file-based modules for Csound. I've posted a summary at:
> > >
> > > https://github.com/csound/csound/issues/2340
> > >
> > > The idea for backwards compatibility is that #include works as-is but
> > > import uses the proposed module-based system, and to encourage users
> > > to adopt import over #include moving forward.
> > >
> > > I think for feedback it might be good to carry on on the github issue
> > > rather than on the mailing list here.
> > >
> > > Thanks!
> > > steven

I don't know if I like the idea, I prefer global objects to be created as such and instr0 variables to be local to instr0 so we can keep them completely separate from instruments. Not sure also whether this would bring backwards compat issues.

I also think it is good to be able to be definite about global variables.

Also at this stage I prefer if we don't backtrack on key decisions made regarding the language, such as the global attribute. I have written a lot of code and examples (it's been a year so since they were brought in).

I like the idea of modules etc but they should not be dealing the release of Csound 7. Once Hlodver's PR is merged we have completed the work for 7.0. The rest can be added later, otherwise we will never finish it.

Prof. Victor Lazzarini
Maynooth University
Ireland

> On 5 Nov 2025, at 17:15, Steven Yi  wrote:
>
> Another note: I'm currently deep in the module system implementation
> and am working through some design things that have come up. The idea
> of global vars is a little interesting in the context of modules, and
> I might be under the influence of Python's design at the moment, but
> the idea right now I have is:
>
> 1. any var in "instr 0" space is just global, and is "module global"
> 2. Accessing a global from an instrument traditionally is done by
> g-vars. We could have it similar to python where you can access
> globals by default without using global, but use global if you need to
> write to them:
>
> ```
> bus1:a init 0
> bus2:a init 0
>
> instr Test
>  global bus1, bus2
>  bus1 += oscili(0.25, 440)
>  bus2 += oscili(0.25, 550)
> endin
> ```
>
> 3. g-vars become grandfathered in but above becomes best practice
> moving forward.
>
> The reason this needs some clarification is for importing and using
> vars from a module. For example, you might have:
>
> config.orc:
> ```
> maxNotes:i = 32
> ```
>
> test.orc:
> ```
> import config
>
> maxalloc(1, config.maxNotes)
> ```
>
> I think this looks clear and also gets rid of the awkward
> `myVar@global:i` syntax.
>
> Thoughts? I'm still looking at other languages and module
> implementations to get ideas, but so far this is the leading candidate
> in my mind, considering we have to recontextualize what g-vars means
> and how they have been used historically.
>
>
>
>> On Sun, Nov 2, 2025 at 11:50 AM Steven Yi  wrote:
>>
>> I think it'll be tricky but worth it.
>>
>> Just a note, I revised the proposal in the PR to focus on using
>> Python-style import syntax rather than Javascript. This is mainly
>> because JS ties in object destructuring syntax into its import system,
>> which works well but it isn't something that makes sense with Csound
>> IMO. Python's import syntax is pretty clear to me and I think it would
>> fit in nicely with Csound orc language. The one thing would be that
>> we'd have to use a convention for file names (i.e., files must end in
>> .orc, similar to how python modules have to be files that end in .py
>> or .pyc).
>>
>>> On Fri, Oct 31, 2025 at 1:48 PM Victor Lazzarini
>>> <000010b17ddd988e-dmarc-request@listserv.heanet.ie> wrote:
>>>
>>> Looks good to me, but sounds like hard work.
>>>
>>> I think fixing name clashes is a very good idea, in fact something essential really even outside the scope of this module system.
>>>
>>> Prof. Victor Lazzarini
>>> Maynooth University
>>> Ireland
>>>
>>>> On 31 Oct 2025, at 17:06, Steven Yi  wrote:
>>>>
>>>> *Warning*
>>>>
>>>> This email originated from outside of Maynooth University's Mail System. Do not reply, click links or open attachments unless you recognise the sender and know the content is safe.
>>>>
>>>> Hi All,
>>>>
>>>> I did some brainstorming in a long session with AI and produced a plan
>>>> for file-based modules for Csound. I've posted a summary at:
>>>>
>>>> https://github.com/csound/csound/issues/2340
>>>>
>>>> The idea for backwards compatibility is that #include works as-is but
>>>> import uses the proposed module-based system, and to encourage users
>>>> to adopt import over #include moving forward.
>>>>
>>>> I think for feedback it might be good to carry on on the github issue
>>>> rather than on the mailing list here.
>>>>
>>>> Thanks!
>>>> steven

Hmm, after diving into looking at module systems, I'm finding I don't
like the @global syntax as much as thinking in terms of python's
scoping rules, but at the same time, it's in-line with the historical
g-vars so it's consistent. I would have liked to have had instr0 vars
accessible within the module without any @global (looking back, I had
raised that as part of the original thread discussing globals and
explicit vars), but looks like that's not going to be possible. It'll
be awkward for writing IMO, but seems like it'll work, so @global's
will be module global, and you'll need to mark that as such to access
outside of the module, such as:


config.orc:
```
maxNotes@global:i = 32
```

test.orc:
```
import config

maxalloc(1, config.maxNotes)
```

As a side note, we could have probably gone with a keyword such as:

global maxNotes:i = 32

We might consider this for the future if we add other modifiers like:

// global, immutable
global const maxNotes:i = 32


As for scheduling of the module system, it can follow up after 7.0
initial release. We'll need time to test as a community to iron out
any issues as well as update documentation.

On Wed, Nov 5, 2025 at 3:00 PM Victor Lazzarini
<000010b17ddd988e-dmarc-request@listserv.heanet.ie> wrote:
>
> I don't know if I like the idea, I prefer global objects to be created as such and instr0 variables to be local to instr0 so we can keep them completely separate from instruments. Not sure also whether this would bring backwards compat issues.
>
> I also think it is good to be able to be definite about global variables.
>
> Also at this stage I prefer if we don't backtrack on key decisions made regarding the language, such as the global attribute. I have written a lot of code and examples (it's been a year so since they were brought in).
>
> I like the idea of modules etc but they should not be dealing the release of Csound 7. Once Hlodver's PR is merged we have completed the work for 7.0. The rest can be added later, otherwise we will never finish it.
>
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
>
> > On 5 Nov 2025, at 17:15, Steven Yi  wrote:
> >
> > Another note: I'm currently deep in the module system implementation
> > and am working through some design things that have come up. The idea
> > of global vars is a little interesting in the context of modules, and
> > I might be under the influence of Python's design at the moment, but
> > the idea right now I have is:
> >
> > 1. any var in "instr 0" space is just global, and is "module global"
> > 2. Accessing a global from an instrument traditionally is done by
> > g-vars. We could have it similar to python where you can access
> > globals by default without using global, but use global if you need to
> > write to them:
> >
> > ```
> > bus1:a init 0
> > bus2:a init 0
> >
> > instr Test
> >  global bus1, bus2
> >  bus1 += oscili(0.25, 440)
> >  bus2 += oscili(0.25, 550)
> > endin
> > ```
> >
> > 3. g-vars become grandfathered in but above becomes best practice
> > moving forward.
> >
> > The reason this needs some clarification is for importing and using
> > vars from a module. For example, you might have:
> >
> > config.orc:
> > ```
> > maxNotes:i = 32
> > ```
> >
> > test.orc:
> > ```
> > import config
> >
> > maxalloc(1, config.maxNotes)
> > ```
> >
> > I think this looks clear and also gets rid of the awkward
> > `myVar@global:i` syntax.
> >
> > Thoughts? I'm still looking at other languages and module
> > implementations to get ideas, but so far this is the leading candidate
> > in my mind, considering we have to recontextualize what g-vars means
> > and how they have been used historically.
> >
> >
> >
> >> On Sun, Nov 2, 2025 at 11:50 AM Steven Yi  wrote:
> >>
> >> I think it'll be tricky but worth it.
> >>
> >> Just a note, I revised the proposal in the PR to focus on using
> >> Python-style import syntax rather than Javascript. This is mainly
> >> because JS ties in object destructuring syntax into its import system,
> >> which works well but it isn't something that makes sense with Csound
> >> IMO. Python's import syntax is pretty clear to me and I think it would
> >> fit in nicely with Csound orc language. The one thing would be that
> >> we'd have to use a convention for file names (i.e., files must end in
> >> .orc, similar to how python modules have to be files that end in .py
> >> or .pyc).
> >>
> >>> On Fri, Oct 31, 2025 at 1:48 PM Victor Lazzarini
> >>> <000010b17ddd988e-dmarc-request@listserv.heanet.ie> wrote:
> >>>
> >>> Looks good to me, but sounds like hard work.
> >>>
> >>> I think fixing name clashes is a very good idea, in fact something essential really even outside the scope of this module system.
> >>>
> >>> Prof. Victor Lazzarini
> >>> Maynooth University
> >>> Ireland
> >>>
> >>>> On 31 Oct 2025, at 17:06, Steven Yi  wrote:
> >>>>
> >>>> *Warning*
> >>>>
> >>>> This email originated from outside of Maynooth University's Mail System. Do not reply, click links or open attachments unless you recognise the sender and know the content is safe.
> >>>>
> >>>> Hi All,
> >>>>
> >>>> I did some brainstorming in a long session with AI and produced a plan
> >>>> for file-based modules for Csound. I've posted a summary at:
> >>>>
> >>>> https://github.com/csound/csound/issues/2340
> >>>>
> >>>> The idea for backwards compatibility is that #include works as-is but
> >>>> import uses the proposed module-based system, and to encourage users
> >>>> to adopt import over #include moving forward.
> >>>>
> >>>> I think for feedback it might be good to carry on on the github issue
> >>>> rather than on the mailing list here.
> >>>>
> >>>> Thanks!
> >>>> steven