Go and Shell can skip this page
Go does have a notion of source roots: where your `
go.mod
` is located. However, that is handled automatically by Pants without you needing to follow this page.Shell does not have any notion of source roots.
# What are source roots?
Some project layouts use top-level folders for namespace purposes, but have the code live underneath. However, the code's imports will ignore these top-level folders, thanks to mechanisms like the `$PYTHONPATH
` and the JVM classpath. _Source roots_ are a generic equivalent of these concepts.
For example, given this Python project:
You would likely set `PYTHONPATH=src/python
` and use imports like this:
In the example above, `src/python
` is a source root. So, when some code says `from project.app import App
`, Pants can know that this corresponds to the code in `src/python/project/app.py
`.
# Configuring source roots
There are two ways to configure source roots:
Using patterns
Using marker files
You can mix and match between both styles. Run `./pants roots
` to see what Pants is using:
## Configuring source roots using patterns
You can provide a set of patterns that match your source roots:
The `/
` prefix means that the source root is located at the build root, so it will match `src/python
`, but not `project1/src/python
`.
You can leave off the `/
` prefix to match any directory whose suffix matches a pattern. For example, `root_patterns = ["src/python"]
` would consider all of these to be source roots, if they exist:
`
src/python
``
project1/src/python
`
You can use `*
` as a glob. For example, `root_patterns = ["/src/*"]
` would consider all of these to be source roots:
`
src/python
``
src/java
``
src/assets
`
### Configuring no source roots
Many projects do not have any top-level folders used for namespacing.
For example, given this Python project:
You would likely _not_ set `PYTHONPATH
` and would still use imports like this:
If you have no source roots, use this config:
Default source roots
The default value of the `
root_patterns
` config key is `["/", "src", "src/python", "src/py", "src/java", "src/scala", "src/thrift", "src/protos", "src/protobuf"]
`.These capture a range of common cases, including a source root at the root of the repository. If your source roots match these patterns, you don't need to explicitly configure them.
## Configuring source roots using marker files
You can also denote your source roots using specially-named marker files. To do so, first pick a name (or multiple names) to use:
Then, place a file of that name in each of the source roots. The contents of those files don't matter. They can be empty.
For example, given this Python repo, where we have a `setup.py
` for each distinct project:
We could use this config:
We can then run `./pants roots
` to find these source roots used:
This means that Pants would work with these imports:
Whereas these imports are invalid:
# Examples
These project structures are all valid; Pants does not expect you to reorganize your codebase to use the tool.
## `src/<lang>
` setup
This setup is common in "polyglot" repositories: i.e. repos with multiple languages.
### Project:
While we have tests in a separate source root here, it's also valid to have tests colocated with their src files.
### Example imports:
### Config:
Note that we organized our 3rdparty requirements in the top-level folders `3rdparty/python
` and `3rdparty/java
`, but we do not need to include them as source roots because we do not have any first-party code there.
## Multiple top-level projects
### Project:
This layout has lots of nesting; this is only one possible way to organize the repository.
### Example imports:
Note that even though the projects live in different top-level folders, you are still able to import from other projects. If you would like to limit this, you can use `./pants dependees
` or `./pants dependencies
` in CI to track where imports are being used. See [Project introspection](🔗).
### Config:
Either of these are valid and they have the same result:
## No source root
Warning: while this project structure is valid, it often does not scale as well as your codebase grows, such as adding new languages.
### Project:
### Example imports:
### Config:
Either of these are valid and they have the same result: