Development Tools
This section goes over some of the many tools that will help make development easier. None of these tools are an absolute requirement for development.
Docker
Docker is a lightweight virtualization solution, allowing you to containerize software that needs to run in a Linux runtime environment. Windows, MacOS and Linux all provide options to run Docker containers. Visit https://docs.docker.com/get-docker/ for installation and configuration instructions for your Operating System.
Docker Compose
This project also uses an orchestration tool for Docker, called Docker Compose. Docker Compose reads a configuration file that may contain one or more containers, along with their runtime settings, such as disk volumes mounts, network routes and environment variables. For installation and configuration, follow the documentation at https://docs.docker.com/compose/.
Visual Studio Code
Visual Studio Code, or VS Code, is an IDE created and maintained by Microsoft. It's a powerful editor that uses an extension marketplace to provide additional functionality to its core features. One such feature is Remote Containers, which allows VS Code to interact with Docker. This allows you to setup a custom development environment inside a Docker container. For instructions on installing VS Code, please visit https://code.visualstudio.com/download.
Clone the Repository in a Container Volume
We recommend that you clone the source repository inside a Docker volume and develop from within this container environment. This will provide you with all of the tools you will need for development, along with a experience that is consistent and well tested with what we have used for development. By using a Docker Volume for storage, you will also gain some file system performance when running under MacOS or Windows, over bind-mounted volumes.
After you have installed everything, begin, by opening VS Code, either by launching by command-line (or from a GUI shortcut):
code
Using the Command Palette (Show All Commands), bring up a list
of command options and select: Remote-Containers:
Clone Repository in Named Container Volume...
This will prompt you for the url to the GitHub repository.
-
Enter
https://github.com/afw-org/afw.git -
Select
Create a new volume... -
Accept the default name
vsc-remote-containers -
Accept the default repository name
afw
The first time this is performed, Docker may take a long time to download the appropriate software dependencies.
Using the VS Code Tasks
Once the development Docker Container is running, you can do anything manually, from the built-in terminal that VS Code provides. In addition, there are various VS Code "tasks" that are available to perform many of these steps.
- Build: Everything
- Build: afwdev build
- Build: afwdev build --cdev
- Build: Administrative Web Application
- Start: nginx
- Start: afwfcgi
- Start: Administrative Web Application
- afwdev: Generate
- afwdev: Core Tests
Creating a Multi-Root Workspace
If you plan to develop extensions or applications, outside of
the afw core folder, you may want to create
a workspace to contain both core and your extensions and apps.
You can do so by selecting File -> Save Workspace As from the menu bar. This will prompt you for a
location within your Docker Volume to save the workspace
file (afw.code-workspace by default).
Choose a location outside of all of your project
repository paths. For example, /workspaces.
Once you have saved the workspace, you can add additional
project repository folders to your workspace by using the
File->Add Folder to Workspace... command.