{"id":17334393,"url":"https://github.com/marshallasch/ns3-action","last_synced_at":"2026-01-12T07:28:29.728Z","repository":{"id":40478086,"uuid":"356635431","full_name":"MarshallAsch/ns3-action","owner":"MarshallAsch","description":"a test action for ns-3","archived":false,"fork":false,"pushed_at":"2024-06-19T17:38:55.000Z","size":39,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T11:41:16.663Z","etag":null,"topics":["actions","cicd","docker","ns3"],"latest_commit_sha":null,"homepage":"https://github.com/marketplace/actions/ns-3-compile-checker","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarshallAsch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"marshallasch","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://www.paypal.me/marshallasch"]}},"created_at":"2021-04-10T16:22:06.000Z","updated_at":"2022-01-08T22:35:56.000Z","dependencies_parsed_at":"2024-10-28T14:26:13.016Z","dependency_job_id":"775579ef-c20d-445c-9da2-54e3841ac6a2","html_url":"https://github.com/MarshallAsch/ns3-action","commit_stats":{"total_commits":34,"total_committers":2,"mean_commits":17.0,"dds":0.02941176470588236,"last_synced_commit":"949ffa1c923438da71b3bfc2abf10422e9f10db0"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshallAsch%2Fns3-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshallAsch%2Fns3-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshallAsch%2Fns3-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshallAsch%2Fns3-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarshallAsch","download_url":"https://codeload.github.com/MarshallAsch/ns3-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247046600,"owners_count":20874685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","cicd","docker","ns3"],"created_at":"2024-10-15T15:05:56.681Z","updated_at":"2026-01-12T07:28:29.689Z","avatar_url":"https://github.com/MarshallAsch.png","language":"Shell","funding_links":["https://github.com/sponsors/marshallasch","https://www.paypal.me/marshallasch"],"categories":[],"sub_categories":[],"readme":"[![Create Docker Container](https://github.com/MarshallAsch/ns3-action/actions/workflows/deploy.yaml/badge.svg)](https://github.com/MarshallAsch/ns3-action/actions/workflows/deploy.yaml)![GitHub](https://img.shields.io/github/license/marshallasch/ns3-action?style=plastic)\n![Lines of code](https://img.shields.io/tokei/lines/github/marshallasch/ns3-action?style=plastic)\n![NS3 version](https://img.shields.io/badge/NS--3-3.32-blueviolet?style=plastic)\n![NS3 version](https://img.shields.io/badge/NS--3-3.33-blueviolet?style=plastic)\n![NS3 version](https://img.shields.io/badge/NS--3-3.34-blueviolet?style=plastic)\n![NS3 version](https://img.shields.io/badge/NS--3-3.35-blueviolet?style=plastic)\n\n![Docker Pulls](https://img.shields.io/docker/pulls/marshallasch/ns3-action?style=plastic)\n\n# NS3 CI Checker\n\nThis action is used to test [NS3](https://www.nsnam.org/) simulation code to check that it builds\nand that a simple simulation can run without crashing. \n\nThis action can be used to check your code for multiple versions of ns-3, currently this will support\n`ns-3.32`, `ns-3.33`, `ns-3.34`, and `ns-3.35`.\nIf you wish to see a different version of ns3 supported by this action open an issue and Id be happy to add support for it. \n\n\n## Motivation\n\nThe ns-3 network simulation platform is an interesting codebase that is different from most other\nlibrary projects, where instead of including the simulator as a project dependency the simulation\ncode needs to be written _inside_ of the simulator code.\nThis presents some challenges with doing CI/CD testing on the simulation code that is being\nwritten because you can not check to make sure that the code compiles without also compiling the \nentire simulator as well.\nThis is an extremely time consuming process (the github action to build this container takes about 23\nminutes to run), that is no good for a simple \"does this compile check\", hence this project.\n\n## Building\n\nThis repository is not meant to be built or used on its own, however it can be built manually.\nThe only dependency needed to build this is docker, and more than 2 GB of ram, I think 4GB might be needed\nor it will crash part way through. \n\n```bash\n$ docker build \\\n    --build-arg VCS_REF=$(git rev-parse -q --verify HEAD) \\\n    --build-arg BUILD_DATE=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\") \\\n    --build-arg NS3_VERSION=3.32 \\\n    -t marshallasch/ns3-action .\n```\n\nBy default it will use ns-3 version 3.32, as that is the version of the simulator that I am using for my\nresearch.\nBut a different version can be specified:\n\n```bash\n$ docker build --build-arg NS3_VERSION=3.33 marshallasch/ns3-action .\n```\n\n## Usage\n\n### Inputs\n\n\n#### `sim_name`\n\n**optional** The extra options that are passed to the `./waf --run \"\u003csimulation name\u003e  \u003coptions\u003e\"` \nto test run the simulation. \nOnly specify this if the `location` is being set to something other than `scratch`, \notherwise it is ignored.\n\n#### `sim_args`\n\n**optional** The extra options that are passed to the `./waf --run \"\u003csimulation name\u003e \u003coptions\u003e\"` \nto test run the simulation. \nIt is also important to note that this container is not designed to actually run simulations in\nand these arguments should be  selected so that the smallest possible simulation can be run to ensure\nthat the code works. \n\n#### `pre_run`\n\n**optional** A script that can be specified to run before the simulation code get compiled or run.\n\nNote that this will be run from the NS3 directory, the script directory must be relative to the repository root and should not include a leading '/'\nThe ns-3 root installation location can be accessed through the `NS3_ROOT` envirionment variable.\nThe module can be accessed through the `NS3_MODULE` environment variable.\n\n#### `post_run`\n\n**optional** A script that can be specified to run before the simulation code get compiled or run. If this is specified then the return value of this script is used.\n\nNote that this will be run from the NS3 directory, the script directory must be relative to the repository root and should not include a leading '/'\nThe ns-3 root installation location can be accessed through the `NS3_ROOT` envirionment variable.                       \nThe module can be accessed through the `NS3_MODULE` environment variable. \n\n#### `location`\n\n**optional** The location that the simulation code should be copied.\nThis should only be one of `scratch`, `src`, or `contrib`. \nThe value will default to `scratch` if it is not set.\nIf it is set to `scratch` then the `sim_name` field is optional, for any other value it is required.\n\n\n\nAlso note that there is no output that is collected from this container and it is only used to check\nthat 1) the code builds, and 2) that the code runs without crashing. \n\n### Example usage\n\n```yaml\nname: build-ns3\n\non: [push, pull_request]\n\njobs:\n  build-on-ns3:\n    runs-on: ubuntu-latest\n\n    steps:\n    - uses: actions/checkout@v2\n    - name: ns3 build\n      uses: marshallasch/ns3-action@32.1\n      with:\n        location: 'contrib'\n        sim_name: 'saf-example'\n        sim_args: '--run-time=900 --total-nodes=5'\n```\n\n## Special Thanks\n\nI would like to acknowledge Dr. Jason Ernst ([@compscidr](https://github.com/compscidr))\nwho gave me the idea to implement this pipeline stage to help validate that my simulation code\nactually builds. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarshallasch%2Fns3-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarshallasch%2Fns3-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarshallasch%2Fns3-action/lists"}