mirror of
https://git.numenor-labs.us/dsfx.git
synced 2025-04-29 16:20:34 +00:00
112 lines
5.4 KiB
Markdown
112 lines
5.4 KiB
Markdown
# Hacking
|
|
|
|
Welcome fellow hacker! This document is intended to help you get started with the codebase and
|
|
understand how to use the various tools and libraries that are included. If you have any questions,
|
|
please feel free to reach out to the maintainers.
|
|
|
|
**Index**
|
|
|
|
- [File Structure](#file-structure)
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
There are three folders on the top level of the project. They are:
|
|
|
|
- [cmd](#cmd)
|
|
- [docs](#docs)
|
|
- [internal](#internal)
|
|
|
|
Files that are stored in the root of the project are generally used for configuration and
|
|
documentation purposes, but we try to keep the number of files in the root of the project to a
|
|
minimum.
|
|
|
|
Currently we have the following files in the top level:
|
|
|
|
- `.gitignore` - This file is used to tell git which files and directories to ignore when
|
|
committing changes to the repository.
|
|
- `CHANGELOG.md` - This file is used to keep track of changes made to the codebase. It is
|
|
currently unused and reserved for future use.
|
|
- `go.mod` - This file is used to manage the dependencies of the project. It is used by the Go
|
|
module system to track the dependencies of the project and ensure that the correct versions are
|
|
used. Our project does not have any external dependencies, so this file primarily serves to
|
|
establish the project as a Go module.
|
|
- `README.md` - This file is used to provide information about the project. It is used to
|
|
document the project and provide instructions for how to use it. This file is intended to be
|
|
used as a reference for developers and users of the project.
|
|
|
|
### cmd
|
|
|
|
The `cmd` directory contains entry points for the various tools that are included in the project.
|
|
Currently these are the `dsfx` and `dsfxctl` tools. They each define Go `main` packages that can
|
|
be compiled and distributed.
|
|
|
|
In general, code in this directory should be relevant to the starting, stopping, and running of the
|
|
tools. It should not contain any business logic or other code that is not relevant to the tool
|
|
itself. Rather, it should delegate to the code in the `internal` directory to do the actual work
|
|
and serve as a thin bootstrapping layer.
|
|
|
|
### docs
|
|
|
|
The `docs` directory contains documentation for the project. Files that are children of this folder
|
|
are intended to be viewed by end users. Feel free to peruse around and learn about the system.
|
|
|
|
Files that are located in `docs/internals` are **not** intended for end users. They are intended for
|
|
developers and contributors to the project. These files are intended to be used as a reference for
|
|
understanding the codebase and how it works. The file you are reading right now is located in this
|
|
folder.
|
|
|
|
### internal
|
|
|
|
The `internal` directory contains the core code of the project. This code is not intended for public
|
|
use and is meant for internal use only. The code in this directory is organized into several
|
|
subdirectories, each of which serves a specific purpose.
|
|
|
|
#### internal/client
|
|
|
|
This section contains the client code, which is what a user or admin runs on their local machine to
|
|
interact with their server (see internal/peer). The client code is responsible for sending and
|
|
receiving messages to and from the server, as well as handling user input and output. Currently the
|
|
code for the CLI is located in this package, but we would love to see that moved to the `cmd`
|
|
folder as it is not applicable to the library side of the tool. The direct consumer of this package
|
|
is the `cmd/dsfxctl` main package.
|
|
|
|
#### internal/lib
|
|
|
|
This section contains shared libraries that are used by the rest of the codebase. They aren't
|
|
intended for public use, but can be used freely throughout the rest of the application. Code that
|
|
lives in this section should pay close attention to unit tests and benchmarking, as it is likely
|
|
used in more than on place, which means that changes here are force multipliers for both bugs and
|
|
performance.
|
|
|
|
#### internal/peer
|
|
|
|
This section contains the peer code, which is what the server runs on the remote machine. The peer
|
|
code is responsible for communicating with the client code, other peers, and the filesystem. The
|
|
direct consumer of this package is the `cmd/dsfx` main package.
|
|
|
|
#### internal/sim
|
|
|
|
This section of the codebase contains various helpers for simulating different parts of the system.
|
|
You can use these helpers to simulate latency, corruption, and other external factors inside of
|
|
your unit tests.
|
|
|
|
Currently, these tools are most useful in tests as mock implementations of the system. They are not
|
|
intended for production use. When we build out the simulation framework, these tools will mature
|
|
and be targeted for that use case.
|
|
|
|
#### internal/tool
|
|
|
|
This section of the codebase contains various internal tools and scripts that are used for
|
|
development, testing, and deployment purposes. These tools are not intended for public use and are
|
|
meant for internal use only. Each one is a main package with an executable, usually with a single
|
|
command. Some accept command line arguments, you will need to check the code for those.
|
|
Alternatively, you may run the tool with `-h` to see the available options.
|
|
|
|
The tools in this directory can be loosely compared to a `bin` directory, or maybe a `Makefile`.
|
|
We prioritize using Go for our tools, so we try to stay inside of the Go ecosystem as much as
|
|
possible. We also try to keep the tools as simple as possible, so that they are easy to use and
|
|
understand. It is much better to have a lot of really small, really focused tools than a few
|
|
massive tools that do everything.
|