{"id":25453541,"url":"https://github.com/xcessentials/projectgenerator","last_synced_at":"2025-05-16T14:35:01.053Z","repository":{"id":64060078,"uuid":"85138752","full_name":"XCEssentials/ProjectGenerator","owner":"XCEssentials","description":"[DEPRECATED - use 'XCERepoConfigurator' instead] Describe Xcode project declaratively in pure Swift. See instead 'RepoConfigurator'.","archived":false,"fork":false,"pushed_at":"2017-11-16T03:14:16.000Z","size":119,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T08:49:52.327Z","etag":null,"topics":["generator","project","swift","xcode"],"latest_commit_sha":null,"homepage":"https://github.com/XCEssentials/RepoConfigurator","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XCEssentials.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-16T01:32:42.000Z","updated_at":"2020-09-18T15:13:50.000Z","dependencies_parsed_at":"2022-12-02T10:54:18.433Z","dependency_job_id":null,"html_url":"https://github.com/XCEssentials/ProjectGenerator","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XCEssentials%2FProjectGenerator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XCEssentials%2FProjectGenerator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XCEssentials%2FProjectGenerator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XCEssentials%2FProjectGenerator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XCEssentials","download_url":"https://codeload.github.com/XCEssentials/ProjectGenerator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254547212,"owners_count":22089286,"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":["generator","project","swift","xcode"],"created_at":"2025-02-17T23:55:58.592Z","updated_at":"2025-05-16T14:35:01.009Z","avatar_url":"https://github.com/XCEssentials.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub tag](https://img.shields.io/github/tag/XCEssentials/ProjectGenerator.svg)](https://github.com/XCEssentials/FunctionalState/releases)\n[![license](https://img.shields.io/github/license/XCEssentials/ProjectGenerator.svg)](https://opensource.org/licenses/MIT)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n\n# Introduction\n\nDescribe Xcode project declaratively in pure Swift.\n\n# Problem\n\nXcode uses an undocumented proprietary format for describing project structure, settings, etc. in **`*.xcodeproj`** files. That kind of file is hard to read and understand for a human, impossible to merge without merge conflicts if changes were made on two different local copies of the same repo/project, or even on different branches inside the same repo on the same workstation. That makes working together on the same Xcode project file a nightmare, when you need to merge changes \"*.xcodeproj\" always has conflicts and developers have to resolve them manually, wasting lots of time for routine that might be done by computer. We need a better solution!\n\n# Existing solution\n\nThere is a command line tool that allows developer to write project specification in a form of plain text configuration file (using Ruby or YAML) and then generate **`*.xcodeproj`** file on the fly from this specification - [Struct](https://github.com/workshop/struct).\n\nThe specification file format features very concise hierarchic notation that's easy and intuitive, and you only need to specify explicitly settings which can not be inferred somehow or you need a value that differs from defaults (provided by the tool itself or, most often, by Xcode).\n\nFor vast majority of iOS developers, this tool should be already a good enough solution, but there are still few inconveniences:\n\n- you have to learn a new language/syntax (not every iOS developer knows Ruby and feel comfortable to deal with it on daily basis);\n- you need to leave Xcode and switch to another text editor with proper syntax highlight for Ruby/YAML to edit the specification file, because Xcode does not support YAML and have limited syntax highligh for Ruby;\n- due to nature of Ruby/YAML, you do not have development time syntax check, you have to try to run the tool in order to disciover a syntax error in your specification.\n\n# Wishlist\n\nBased on the downsides of Struct listed above, here is a list of wishes for an \"ideal\" tool like that:\n\n- write project specification in pure Swift;\n- use Xcode to edit specification file;\n- get full syntax highlight and real time syntax check in specification file.\n\n# About this tool\n\nTo archive the goals listed above, this project has been made. Think of it as a thin wrapper on top of [Struct](https://github.com/workshop/struct) CLI tool. It brings no extra functionality in comparison with [Struct](https://github.com/workshop/struct), but adds some convenience to writing project file specification.\n\n# How to install\n\nUse [Carthage](https://github.com/Carthage/Carthage) to install the tool into your project. Put into your [Cartfile](https://github.com/Carthage/Carthage/blob/master/Documentation/Artifacts.md#cartfile):\n\n```ruby\ngithub \"XCEssentials/ProjectGenerator\" ~\u003e 2.1\n```\n\nThe project folder will be downloaded by [Carthage](https://github.com/Carthage/Carthage), but nothing will be built, that's expected behavior, ignor warnings from Carthage.\n\n# How it is organized\n\n**Remember**, you are not supposed to make any changes in the project, except your project specification file.\n\nThe poject consists of 3 main parts, each of them has its own scheme:\n\n1. Scheme **\"Fwk\"** - macOS framework that implements functionality related to parsing your Swift specification file and writing target specification file in YAML for [Struct](https://github.com/workshop/struct).\n2. Scheme **\"Launcher\"** - a command line tool that gets the job done. It includes the framework module as dependency and starts the process of parsing your Swift specification file into [Struct](https://github.com/workshop/struct) YAML spec file. This target contains just 2 source files. First one is the **`main.swift`** file, it will be executed when the target will be run in Xcode. Second file is **`Project.Struct.swift`** and it's missing in the project out of the box intentinonally. It's expected location is in your project root directory (given that `ProjectGenerator` is installed with [Carthage](https://github.com/Carthage/Carthage)) and it's your responsibility to put this file there.\n3. Scheme **\"Example\"** - very similar to the \"Launcher\" scheme, with only difference that it contains a sample Swift project specification file with all the necessery statements isnside. Use this sample Swift specification file as starting point for your project specification.\n\n# How to start using\n\nIf using first time:\n\n1. copy the [sample file](https://github.com/XCEssentials/ProjectGenerator/blob/master/Example/Spec.swift) from [Example](https://github.com/XCEssentials/ProjectGenerator/tree/master/Example) folder to your project root folder and rename it with **`Project.Struct.swift`**;\n2. open the project (from your project root folder, go to `./Carthage/Checkouts/ProjectGenerator`, open file `ProjectGenerator.xcodeproj`), make sure that you have the `Launcher` scheme selected (notice, that if you've done everything correctly at the previous step, the `Project.Struct.swift` under `Launcher` group on Project Navigator panel will be in place, not missing);\n3. make initial editing of the `Project.Struct.swift` file to describe at least basic structure for your project;\n4. when project specification is ready, just hit \"Cmd+R\" hotkey in Xcode (Run the scheme), Xcode will build and run the scheme, a new file named `project.yml` will be created at project root folder. That's it!\n\nTo actually generate project file from the created `project.yml` file - use Struct itself from your project root folder.\n\n# How to use\n\nWhen yoiu need to make a change into your project configuration:\n\n1. open the project (from your project root folder, go to `./Carthage/Checkouts/ProjectGenerator`, open file `ProjectGenerator.xcodeproj`), make sure that you have the `Launcher` scheme selected;\n2. make the necessary changes in the `Project.Struct.swift` file;\n3. run the scheme, a new file named `project.yml` will be created at project root folder (will override previous version).\n\nTo actually (re)generate project file from the newly created `project.yml` file - use Struct itself from your project root folder.\n\n# Notes on versioning\n\nThis project follows [Semantic Versioning](http://semver.org), its MAJOR (and MINOR, when possible) version number is syncronized with corresponding version numbers of the [Struct](https://github.com/workshop/struct) specification format, which is used as blueprint for the output YAML project specification file.\n\nFor example, if this project has version number `2.1.0`, that means the output specification file `project.yml` will be generated using [Spec format: v2.0](https://github.com/workshop/struct/wiki/Spec-format:-v2.0).\n\n## Future plans\n\nThis project will be kept up to date with latest MAJOR version of [Struct](https://github.com/workshop/struct). Also there is a chance that the execution of [Struct](https://github.com/workshop/struct) CLI tool after (re)generation of `project.yml` file will by automated as well, but so far it seems to be a bit out of scope for the tool.\n\n## Contribution, feedback, questions...\n\nIf you want to contirbute to the project - feel free to open a pull request.\n\nIf you have any questions, suggestions, feedback or believe you found a bug - feel free to create an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxcessentials%2Fprojectgenerator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxcessentials%2Fprojectgenerator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxcessentials%2Fprojectgenerator/lists"}