# How to group several modules in a package

**URL:** <https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627>\
**Category:** New to Julia\
**Tags:** packages, book, tutorials\
**Created:** [September 6, 2018, 3:46pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627 "2018-09-06T15:46:09Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 6, 2018, 3:46pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/1 "2018-09-06T15:46:09Z")

</div>

Hello, I have a very basic question how to organize Julia code.

I have written several modules:

- `Perms.jl` module Perms: ports from GAP permutation stuff. Defines functions and extends Base functions (like \*, etc)
- `LaurentPols.jl` module LaurentPols: ports from GAP Laurent polynomials. Defines stuff as above.
- `PermGroups.jl` module PermGroups: ports from GAP permutation group stuff. uses Perms and defines stuff as above.
- `Cycs.jl` module Cycs: ports from GAP cyclotomic numbers. Defines functions and extends Base functions (like \*, etc)

Now I would like to make a package GAP including all the above stuff.

How do I write `GAP.jl` so `using GAP` will automatically imply using all the above packages  
(exporting all the needed names and definitions so they can be used unqualified?)

---

<div class="post-metadata">

**Author:** ![korsbo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/korsbo/32/15942_2.png) [@korsbo](https://discourse.julialang.org/u/korsbo)\
**Post date:** [September 6, 2018, 3:56pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/2 "2018-09-06T15:56:01Z")

</div>

Have a look at [Reexport.jl](https://github.com/simonster/Reexport.jl).

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 6, 2018, 4:39pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/3 "2018-09-06T16:39:24Z")

</div>

Yes. This seems what I need. Since this facility is absent from the Julia language, does it mean the Julia creators think that packages should be organized differently? I wonder…

---

<div class="post-metadata">

**Author:** ![korsbo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/korsbo/32/15942_2.png) [@korsbo](https://discourse.julialang.org/u/korsbo)\
**Post date:** [September 6, 2018, 4:42pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/4 "2018-09-06T16:42:30Z")

</div>

you could always do it the verbose way:

```julia
module MyPkg
    foo() = "hello"
    export foo
end

## in your GAP package:

using MyPkg
export foo

```

or something like that.

Edit:  
Also, just because something is not in Base does not mean that it is a second-class citizen in julia.

---

<div class="post-metadata">

**Author:** ![rdeits](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rdeits/32/286_2.png) [@rdeits](https://discourse.julialang.org/u/rdeits)\
**Post date:** [September 6, 2018, 5:10pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/5 "2018-09-06T17:10:31Z")

</div>

> [@Jean\_Michel](#):
>
> Since this facility is absent from the Julia language, does it mean the Julia creators think that packages should be organized differently? I wonder…

Nope, that’s not a reasonable inference. Reexport.jl works perfectly well as a package, so there is no reason for it to be in Julia base. One of the best features of Julia is the fact that fast generic functions and metaprogramming mean that packages can implement almost anything that Julia itself can do.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 6, 2018, 6:54pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/6 "2018-09-06T18:54:47Z")

</div>

Well, there is at least one reason: documentation. The set of packages which are

- clearly useful
- do not have a controversial design

should be documented with the language documentation. Another example I have met is Memoize.

Otherwise, learning the language properly becomes a haphazard proposition. I have already many times since I started learning Julia 6 months ago learned via discourse something which _should_ be in the language documentation.

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [September 7, 2018, 4:21am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/7 "2018-09-07T04:21:42Z")

</div>

If you learn something on here that you think should already be in the docs, please submit a PR introducing that thing to the docs - julia is open source and everyone is encouraged to contribute. In fact, documentation PRs are the best way to get started contributing to Julia, since you are in the unique position of having learnt something you think should be more easily accessible through the docs. The people who told you about that thing may not even know it’s not documented (although I’d like to know of an example of some core concept from the language that isn’t already in the docs).

The problem with documenting which packages are deemed “good” is that that’s a very subjective thing and has to be checked all the time, in addition to updating the docs for changes in the language. Personally, I much prefer people asking here and getting a current answer than having them ask here “I tried to do x with y as recommended by the documentation, but y is not working. Why are the docs recommending this?” as the latter is much more likely to leave a bad impression (“I don’t know how to do x” in the first case as opposed to “x should be possible with y, but it doesn’t work and now everything’s broken”).

However, I do agree that a better overview of registered packages and their use cases should be available somewhere.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 9:26am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/8 "2018-09-07T09:26:47Z")

</div>

Well, what I am missing most now would be a tutorial “Julia packages for dummies” which would take you by  
the hand assuming only minimal or no knowledge of git and github, and would show you all the steps of making a package with a few modules, using a few other packages. Missing that I am forced to consider discourse as the only available tutorial now, in between sessions trying to understand what the manual says about packages.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [September 7, 2018, 9:45am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/9 "2018-09-07T09:45:56Z")

</div>

> [@Jean\_Michel](#):
>
> take you by the hand assuming only minimal or no knowledge of git and github

Would you expect that the tutorial also covers these? Many excellent (non-Julia-specific) tutorials and books on git are available online, eg

[https://git-scm.com/book/en/v2](https://git-scm.com/book/en/v2)

Github-specific ones are available on Github, including

> **[Hello World - GitHub Docs](https://docs.github.com/en/get-started/quickstart/hello-world)**
>
> Follow this Hello World exercise to get started with GitHub.

> **[GitHub flow - GitHub Docs](https://docs.github.com/en/get-started/quickstart/github-flow)**
>
> Follow GitHub flow to collaborate on projects.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 9:49am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/10 "2018-09-07T09:49:33Z")

</div>

I would not expect that the tutorial _covers_ git and github. However I think one does not need to read a book  
on git to write a Julia package: the barrier to write a Julia package would then be very high. I hope the necessary knowledge about git can fit in one or two pages of the tutorial.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [September 7, 2018, 10:36am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/11 "2018-09-07T10:36:36Z")

</div>

> [@Jean\_Michel](#):
>
> I think one does not need to read a book on git to write a Julia package

It was never implied that reading the _whole_ book is necessary, the book I linked has 3 intro chapters (setup, basics, branching), which would be perfectly adequate. Anything less than this may not be sufficient to make a package or contribute to code.

Also — and this may sound harsh — people who don’t want to make a modicum of investment into learning version control perhaps should not be making a Julia package, as it would quickly face a lot of maintenance issues.

The tooling that is routinely used for Julia packages may look daunting to newcomers (git, a site like Github for issue and PR management, CI, autogenerated documentation), but it is something that is relatively easy to pick up by example. Alternatively, one can wait for [PkgDev to catch up](https://github.com/JuliaLang/PkgDev.jl/pull/144), which should make all of this easier.

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [September 7, 2018, 10:56am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/12 "2018-09-07T10:56:36Z")

</div>

One could argue that CI and automated documentation are both not really a necessity for package development per se - they’re convenience tools used for automating certain dull or repetitive tasks that are no requirement for the creation of a package. As version control is a central point of managing multiple versions of packages and distributing them, I think it’s very reasonable to require a basic understanding of how it’s done. In theory, one should be able to just use any git server, register a package pointing to that server and not even deal with issues or CI via Github.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 11:08am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/13 "2018-09-07T11:08:25Z")

</div>

I do not even know what “CI” means.

---

<div class="post-metadata">

**Author:** ![tobias.knopp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tobias.knopp/32/7551_2.png) [@tobias.knopp](https://discourse.julialang.org/u/tobias.knopp)\
**Post date:** [September 7, 2018, 11:10am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/14 "2018-09-07T11:10:55Z")

</div>

Continuous Integration

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 11:14am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/15 "2018-09-07T11:14:20Z")

</div>

Looking at wikipedia, CI seems to be just a fancy word for “testing software before releasing it”.

This is the occasion for me to ask: the markup allows to put examples in individual functions documentation.  
Already a good test is to run these examples. Is there a functionality/package to run automatically these examples as tests?

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [September 7, 2018, 11:43am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/16 "2018-09-07T11:43:56Z")

</div>

Yes, that’s precisely why I said it’s not necessary for the most basic of package development to know about this. The barrier to entry really is just git - and even of that only the most basic concepts: committing, branching, pushing to a remote - basic version control, really.

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [September 7, 2018, 11:51am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/17 "2018-09-07T11:51:07Z")

</div>

Continous Integration means having some server/service/robot automatically run specified tests on user written code - just so the developer doesn’t have to do that themselves (for example if the developer has no real access to the machine where to code will run or when building and testing the code takes a very long time).

No, and with good reason: The documentation directly above functions is not meant to be a 1:1 runnable example, but rather a quick reference for syntax, accepted arguments and the like. Having tests run automatically is exactly what CI is for - the only thing you have to do in addition to writing tests in `<projectDir>/test/runtests.jl` is telling e.g. Travis how to run tests for your package.

Again, this is not a requirement! One can just as easily run tests for a downloaded package [manually using `(v1.0) pkg> test Example`](https://docs.julialang.org/en/stable/stdlib/Pkg/#Testing-packages-1) (which is what I’m using right now for yet-to-be-published packages).

It seems what you’re asking for is an introduction on how to _publish and maintain_ packages, rather than just creating them, as the latter is covered pretty well in the documentation, while the former is not.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 11:54am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/18 "2018-09-07T11:54:50Z")

</div>

> No, and with good reason: The documentation directly above functions is not meant to be a 1:1 runnable example, but rather a quick reference for syntax, accepted arguments and the like.

If it is not possible to run automatically the examples in markup for each function, but you need to repeat them in a file `runtests.jl` then these examples are less useful than they could be. The need for repetition is always a sign of bad design in computer code.

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [September 7, 2018, 11:58am UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/19 "2018-09-07T11:58:07Z")

</div>

In my opinion, Documentation and actually testing functionality are not very related. Documentation is plain text written for a user, to understand how to use a given function, package, etc. with a lot of (sometimes verbose) explanations. Testing and Unit Tests are just regular code which runs other code and compares outputs to some predetermined target output. They’re not meant to be read and studied. They have fundamentally different goals and are written for an entirely different reason.

Again, Examples are not Testing - they are documentation. Yes, they can be 1:1 runnable - but this does not mean that just running them will cover all possible inputs or use cases.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 12:02pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/20 "2018-09-07T12:02:02Z")

</div>

OK, i am discouraged by your answers. I will give up for the moment the attempt to write a package.

[Next page](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627.md?page=2)