Skip to content

Latest commit

 

History

History
216 lines (149 loc) · 7.9 KB

README.md

File metadata and controls

216 lines (149 loc) · 7.9 KB
Raw

CarthageCache

Build Status Code Climate Test Coverage Gem Version

CarthageCache allows Carthage users to have a shared cache of their Carthage/Build folder backed by Amazon S3.

Most libraries don't provide pre-compiled binaries, .framework files, in their releases. Even if they do, due to Swift lack of ABI, you might be forced to use --no-use-binaries flag and compile all your dependencies. Which, depending on the amount of dependencies and their size it could take significant time.

When you add slow building environments like Travis CI to the mix, a project bootstrap could take around 25 minutes just to build all your dependencies. Which is a lot for every push or pull request. You want your build and test to run really fast.

CarthageCache generates a hash key based on the content of your Cartfile.resolved and the current installed version of Swift. Then it checks if there is a cache archive (a zip file of your Carthage/Build directory) associated to that hash. If there is one it will download it and install it in your project avoiding the need to run carthage bootstrap.

Do you want to improve carthage_cache? Check all the issues tagged with help-wanted!. I'll be more than happy to review your pull request.

Installation

Add this line to your application's Gemfile:

gem 'carthage_cache'

And then execute:

$ bundle

Or install it yourself as:

$ gem install carthage_cache

Setup

AWS credentials

First of all you need to configure your AWS credentials. You can do this by a .carthage_cache.yml file. CarthageCache will try to find this file in the current working directory. It is recommended to generate this file in each project you want to use CarthageCache.

To generate a .carthage_cache.yml you just need to run

carthage_cache config

You can also set your credentials using the following environmental variables

Or if you prefer using AWS Named Profiles, you can use the following environmental variables instead

  • AWS_REGION
  • AWS_PROFILE

AWS S3 bucket

CarthageCache will assume there is a bucket named carthage-cache. You can change the bucket to be used by using the option -b or --bucket-name.

IAM Policy

Once you create the bucket, you will need to create a user. Go to the IAM section and create a new user. Create a new group, and add the new user to that group. Create a policy with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "autogenerated-id",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::carthage-cache"
            ]
        },
        {
            "Sid": "autogenerated-id",
            "Effect": "Allow",
            "Action": [
                "s3:DeleteObject",
                "s3:GetObject",
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::carthage-cache/*"
            ]
        }
    ]
}

Don't forget to attach the policy to the group and make sure to replace autogenerated-id with an ID that should be unique. You can generate a new policy using AWS policy generator and replace the content with the previous snippet keeping the SID field.

Usage

If you want to bootstrap a project from cache and if there is none then fallback to Carthage.

carthage_cache install || carthage bootstrap

If you want to update dependencies and update cache

carthage update && carthage_cache publish

If you want to check whether a cache exists for the current Carfile.resolved

carthage_cache exist

If you want to publish an archive that already exists

carthage_cache publish --force

If you want to delete unused libraries from build directory for all targets

carthage_cache prune

You can also prune the build directory before publishing a new archive

carthage_cache publish --prune-build-directory

Both prune and publish accept --prune-white-list to configure frameworks that don't appear in the Cartfile.resolved and should not be pruned by associating them with a framework that does appear in Cartfile.resolved. Like CocoaLumberjackSwift:

carthage_cache publish -p -w .white-list.yml
  • -p is the short version of --prune-build-directory
  • -w is the short version of --prune-white-list

where .white-list.yml is

"CocoaLumberjackSwift": "CocoaLumberjack"

For more information run the help command

carthage_cache help

OSS project

In an OSS project you wouldn't store AWS credentials anywhere since anyone can have access, even if you have a build like travis that supports for encrypted variables but these are not available in your contributors pull requests build.

In order allow your build to run in these circumstances, you can avoid defining these variables

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_PROFILE

And carthage_cache will work in read-only mode, you wont be able to publish new items but your build will still be able to fetch the cached dependencies.

The only requirement is to make the action s3:GetObject avaible for any anonymous user in your S3 Bucket

{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Sid":"AddPerm",
      "Effect":"Allow",
      "Principal": "*",
      "Action":["s3:GetObject"],
      "Resource":["arn:aws:s3:::examplebucket/*"]
    }
  ]
}

Please know that this will make all your dependencies PUBLIC and accessible for anyone, so if you have sensitive information or proprietary code there you should avoid this configuration.

Project's root directory

The carthage_cache command assumes that the project's root directory is the current working directory and that the Cartfile.resolved file is located in the project's root directory. All carthage_cache accept an optional argument to set the project's root directory. For example

carthage_cache install

Will try to read the Cartfile.resolved file from the current working directory and will install the cache archive in ./Carthage/Build.

carthage_cache install PATH/TO/MY/PROJECT

Will try to read the PATH/TO/MY/PROJECT/Cartfile.resolved and will install the cache archive in PATH/TO/MY/PROJECT/Carthage/Build.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/guidomb/carthage_cache/issues/new.

License

The gem is available as open source under the terms of the MIT License.