Comments (14)
+1 on this thread. If it's something that the Cocoapods team has supported for 4+ years now, it would be great to have documentation for it.
from guides.cocoapods.org.
This continues to be an issue over a year later, and it may have effects the Cocoapods dev team has not foreseen.
One of our clients has an internal podspec repo and we are spending much too much thought on whether we should allow JSON specs or not. No one truly understand what the ramifications are of one vs. the other. The only thing we have to go on right now for JSON format reference is that blog post, plus the examples in the repo.
We don't understand:
- Are there limitations to one or the other?
- Is one the preferred format?
- What is the format? (For the most part it does seem to line up with the Ruby format, but where are the differences?)
- What is the intended future of podspecs? (Support both formats indefinitely? Phase one out someday?)
As far as it goes I'm not seeing a particular demand for this outside of just @irace at the minute too.
This is a self fulfilling prophecy. If you do not document the JSON format and discuss it, demand will of course be extremely low. Even if they learn about it somehow, no one wants to adopt something that has zero public support.
from guides.cocoapods.org.
This post feels a little bit confrontational for bringing up a thread from 2014. Please be more respectful.
The CocoaPods Specs repo is, and always will be JSON. So it's always going to be supported in CocoaPods. We do that so that you don't have to have arbitrary code running on your computer.
Are there limitations to one or the other?
Ruby Podspec are turing-complete, JSON specs are not. They both can turn in the same model objects in CocoaPods though.
Is one the preferred format? What is the format? (For the most part it does seem to line up with the Ruby format, but where are the differences?)
Yes, Ruby.
What is the intended future of podspecs? (Support both formats indefinitely? Phase one out someday?)
The same as it has been, you should be making Ruby podspecs, as this thread shows, if you care enough you can make JSON podspecs but you're going against the grain. No phasing out.
from guides.cocoapods.org.
Apologies if my post sounded confrontational or uncivil. That certainly was not the intention.
And thanks for taking the time to clarify, this is helpful for our team.
from guides.cocoapods.org.
The syntax reference is made by parsing the ruby documentation for the podspec DSL. Additionally, I believe the JSON we accept is stricter than the Ruby, with regards to what my be in an array, etc. @kylef do you know of any good ways of documentating JSON structure?
from guides.cocoapods.org.
I've actually been wanting to create an issue regarding this. I was going to propose we switch documenting for podspecs away from Ruby and into Markdown (or an alternative).
Currently the documentation and specification for a podspec is tightly coupled with our own Ruby implementation. I'd like to suggest we move away from this approach and create a separate specification outside of the implementation for how a pod spec is structured completely away from the code (and the guides). The guides should then be built upon that specification.
The specification should be usable for people to build their own tools to parse JSON pod specs, for example, a pod search engine, or even integrations to clients such as AppCode. Currently there is no concrete specification, only the code documentation embedded in the Ruby DSL.
We have also had issues opened in the past of users who want to contribute to the pod spec "documentation" couldn't figure out how to, unfortunately I can't find any examples of this.
There is a specification called MSON (Markdown Syntax for Object Notation) which allows you to notate object structures right in Markdown. It uses semantics on-top of markdown to provide this, it's similar to JSON Schema. We could also use JSON Schema, however I see many downsides to JSON Schema over Markdown. Since markdown is user friendly and we can render it to HTML directly.
How this might look as a specification
Please note, this is really minimal. I'm just outlining a few features.
Markdown
## Podspec
A specification describes a version of Pod library. It includes details about where the source should be fetched from, what files to use, the build settings to apply, and other general metadata such as its name, version, and description.
- name (string, required) - The name of the pod
- version (SemanticVersion, required) - The version of the pod
- summary (string, required) - A short summary of the pod
- license (License, required) - The license for the pod
This information is used by CocoaPods to generate acknowledgement
files (markdown and plist) which can be used in the acknowledgements
section of the final application.
- homepage (URL, optional) - The URL of the homepage of the Pod.
- source_files (FilePatterns, optional) - The source files of the Pod.
- requires_arc (enum, required)
- (bool)
- (FilePatterns)
## SemanticVersion (string)
A string following semantic versioning.
## License (object)
- type (string, required) - The type of license
- file (string, optional) - The path to the license
- text (string, optional) - The contents of the LICENSE
## URL (string)
A resolvable [RFC3986] URL.
NOTE: Full disclosure, I do work for the company that produced MSON.
- MSON Specification + more examples: https://github.com/apiaryio/mson
- MSON AST: https://github.com/apiaryio/mson-ast
from guides.cocoapods.org.
@kylef That would also mean moving the guides away from Ruby specs as the primary form to JSON, though.
from guides.cocoapods.org.
MSON looks cool. The idea works for me in principal.
Personally, I'm in no rush to re-write large chunks of the guides and de-gut Core when there are issues with significantly more impact on the web side still to do. Others are welcome to dig in though.
Though this doesn't necessarily fix the actual problem that @irace asked for. Which is documentation specifically for the JSON format. It would be shuffling existing docs and then presumably adding it inline. As far as it goes I'm not seeing a particular demand for this outside of just @irace at the minute too.
from guides.cocoapods.org.
As far as it goes I'm not seeing a particular demand for this outside of just @irace at the minute too.
This is probably true. The lack of documentation isn't really impacting me specifically, but I think this raises a bigger question which is: are JSON podspecs intended to be on equal footing with their Ruby equivalents? They seem to be pretty clearly a second class citizen.
From my perspective, this seems less than ideal. Just about every iOS developer is familiar with JSON, while Ruby DSLs raise the barrier to entry (not by much, but at least somewhat).
Additionally, since JSON is what the Specs
repo contains, it's bizarre to context-shift between writing specs in one format (ostensibly Ruby, since that's what anyone who looks at the documentation will see) and reading them in another (unless I'm the only person who actually reads through specs in the repo while researching a potential new dependency).
The blog post introducing Trunk addressed the dichotomy of spec formats as follows:
Will the specs in the Ruby format be deprecated?
No, they are here to stay and are the preferred method if you need to be able to perform automatic generation, such as collecting a list of all the source files from disk. The pod trunk push command will take care of converting the podspec to JSON. This means that you do not have to change any existing podspecs.
The preferred method if you need to be able to perform automatic generation. Since I don't, and since I've never written a line of Ruby outside of my own Podfiles or Podspecs, I was happy to switch over to using JSON for all of my specs (and even start playing around with some tooling).
But I keep running into things that make it seem as though JSON is only being supported somewhat begrudgingly.
from guides.cocoapods.org.
Which brings me to another point I guess, I said I wasn't planning on doing it back in 2014, I'm not definitely not going to build it into the guides in 2016, so this issue can probably be closed.
If someone makes a PR adding it all, I'm game for discussing it there, but I'm not planning on adding support.
from guides.cocoapods.org.
Agree with @orta, please keep discourse civil.
The same as it has been, you should be making Ruby podspecs, as this thread shows, if you care enough you can make JSON podspecs but you're going against the grain.
If this is the case due to lack of resources on the CocoaPods team to fully document the JSON pod spec file, audit all the places in which the CocoaPods CLI tools assume Ruby, etc., I 100% understand.
If this is an explicit design decision, I'd love more context around why.
from guides.cocoapods.org.
Nah, not an explicit design decision, Ruby offers more dev freedom and easily is transformed into the other.
from guides.cocoapods.org.
Thanks!
I’d like to think that, all things being equal, JSON would be the preferred format while Ruby would still be there for power users.
But all things aren’t equal and considering I’m not spending my own time making this so, no complaints from me 👍 👍
from guides.cocoapods.org.
hah - but yeah, I know where your coming from.
from guides.cocoapods.org.
Related Issues (20)
- CocoaPods search api not working HOT 1
- Add documentation for vendored_frameworks HOT 3
- Add documentation for singular vs plural form of properties HOT 1
- Should the Manifest.lock file be added to git or not? HOT 9
- Google Map,Place, Picker Pod not installing HOT 2
- Google Map, Place, Picker HOT 1
- 请问如何遍历project或者遍历workspace的target HOT 1
- isssuuuussssseeee.secting
- ussrss.view HOT 1
- Can import a package of swiftpackage By using cocopods?
- how to push private reops HOT 1
- 更新到移动广告 SDK 7.15.0 或更高版本。
- sdk
- Learning
- pod 'Google-Mobile-Ads-SDK'
- could the symlink gcc issue be more prominent ? HOT 3
- Can I get pod install or pod update return result
- Unable to publish pod after successful push HOT 2
- Easily-to-fall-into Antipattern with Resource Bundle Names HOT 1
- How to include Privacy manifest in the static framework? How to tell cocoa-pods to embed the static framework?
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from guides.cocoapods.org.