enhance dockerized development environment

Add an option to control which PHP version is to be used in devenv service
via PHP env var passed at the time when dev-shell is started (or any dev-*
target is build).

Author: lavarou

Makefile

@@ -475,24 +475,27 @@ test-services-stop:
 # Docker Development Environment
 #
 
-dev-shell:
-	docker compose --profile dev up --build --remove-orphans -d
+devenv-image:
+	@docker compose --profile dev build devenv
+
+dev-shell: devenv-image
+	docker compose --profile dev up --pull --remove-orphans -d
 	docker compose exec -it devenv bash -c "sh files/set_path.sh ; bash"
 
-dev-build:
-	docker compose --profile dev up --build --remove-orphans -d
+dev-build: devenv-image
+	docker compose --profile dev up --pull --remove-orphans -d
 	docker compose exec -it devenv bash -c "sh files/set_path.sh ; make -j4 all"
 
-dev-unit-tests:
-	docker compose --profile dev up --build --remove-orphans -d
+dev-unit-tests: devenv-image
+	docker compose --profile dev up --pull --remove-orphans -d
 	docker compose exec -it devenv bash -c "sh files/set_path.sh ; make -j4 valgrind"
 
-dev-integration-tests:
-	docker compose --profile dev up --build --remove-orphans -d
+dev-integration-tests: devenv-image
+	docker compose --profile dev up --pull --remove-orphans -d
 	docker compose exec -it devenv bash -c "sh files/set_path.sh ; ./bin/integration_runner -agent ./agent/.libs/newrelic.so"
 
-dev-all:
-	docker compose --profile dev up --build --remove-orphans -d
+dev-all: devenv-image
+	docker compose --profile dev up --pull --remove-orphans -d
 	docker compose exec -it devenv bash -c "sh files/set_path.sh ; make -j4 all valgrind; ./bin/integration_runner -agent ./agent/.libs/newrelic.so"
 
 dev-stop:

docker-compose.yaml

@@ -75,6 +75,8 @@ services:
     build:
       context: .
       dockerfile: files/Dockerfile
+      args:
+        PHP_VER: ${PHP:-8.3}
     user: ${UID}:${GID}
     environment:
       MEMCACHE_HOST: memcached

docs/dev_environment.md

@@ -6,19 +6,38 @@ The dockerized development environment prototype allows contributors to both dev
 
 docker-compose spins up `mysql` and `redis` and other databases in separate containers.
 
-Two environment variables to note:
-`NEWRELIC_LICENSE_KEY` is required to run the integration tests and should be set to your NR license key.
-If your collector isn’t the default (collector.newrelic.com), set the `NEWRELIC_COLLECTOR_HOST` to the appropriate value.
+## Prerequisites
 
-PHP_VER can also be set to vary the PHP version being used.
+### 1. Docker Compose
 
-Set all environment variables prior to running the development environment.  
+Dockerized development environment for the New Relic PHP Agent uses following Docker Compose services as a runtime platform. So you need `docker` with `docker compose` installed.
+
+### 2. Environment variables
+
+Dockerized development environment for the New Relic PHP Agent needs a valid license key available in `NEW_RELIC_LICENSE_KEY` environment variable.
+This environment variable must be set prior to starting Dockerized development environment for the New Relic PHP Agent. The easiest way to set
+`NEW_RELIC_LICENSE_KEY` environment variable is via `.env` file. Simply create `.env` file in the top level directory, and add definition
+of `NEW_RELIC_LICENSE_KEY` environment variable there, e.g.:
+```
+NEW_RELIC_LICENSE_KEY=...
+```
+
+The second, optional environment variable, that controls PHP version in Dockerized development environment for the New Relic PHP Agent is `PHP`. `PHP` defaults to latest PHP supported by the agent.
+This environment variable can be provided at the time when Dockerized development environment for the New Relic PHP Agent is started, e.g.:
+```
+make dev-shell PHP=8.2
+```
 
 ## Options for using the environment
 
-## With a shell environment
+### With a shell environment
+
+To start the dev environment type `make dev-shell`.  This will spin up `devenv` service in `agent-devenv` container, with:
+ - latest PHP supported by the agent (this can be overriden with `PHP` environment variable like this: `make dev-shell PHP=8.2`)
+ - all the tools needed to build the agent
+ - all the tools needed to run unit tests
+ - all the tools and supporting services to run integration tests
 
-To start the dev environment type `make dev-shell`.  This will create a set of docker containers.
 A prompt will open and you’ll be able to compile and run all `make` commands right away with no additional setup (for example: `make -j4 all` or `make -j4 valgrind` or `make -j4 run_tests`).
 
 After compiling the agent, the integration tests can be run using the `integration_runner`.
@@ -31,27 +50,27 @@ To end the session type `exit`.  You can run `make dev-stop` to stop the docker-
 
 In the shell, you can run all `make` commands as you normally would.
 
-## Build only
+### Build only
 
 `make dev-build`
 
-## Unit Tests only
+### Unit Tests only
 
 `make dev-unit tests`
 
-## Integration Tests only
+### Integration Tests only
 
 `make dev-integration-tests`
 
-## Build and test all
+### Build and test all
 
 `make dev-all`
 
-## Stop all containers
+### Stop all containers
 
 `make dev-stop`
 
-# Next steps and issues
+## Next steps and issues
 
-## There is possibly some incompatibility with mysql in the main build container as one of the mysql unit tests fails.  Unless this is resolved, It might make sense at a future point to have the integration tests run from a different container than the build container.
+### There is possibly some incompatibility with mysql in the main build container as one of the mysql unit tests fails.  Unless this is resolved, It might make sense at a future point to have the integration tests run from a different container than the build container.