Archive for the ‘Documentation’ Category

libiconv from OS X and Mac Port, and change of Xcode behavior

I have an old project for converting wrongly encoded Korean to properly encode to properly encoded one in mp3 files.

However due to file system corruption while in upgrading to OS X 10.11.6,  I had to rebuild the project again. I found out that I had another project for the same purpose to use different ID3 library. I didn’t remember which project was correct one.

I finally identified the correct one, but had some issues. It was built previously without a problem, but it failed this time. It could be due to changes in Xcode. Yes. there is such change. I will talk about that after taking about difference of libiconv from OS X and Mac Port.

When tried to build, it complaint _iconv, _iconv_open, _iconv_close were missing.
I recalled that there was difference between libiconv from OS X and Mac Port, and there was a comment I wrote for that, but didn’t remember its detailed reasoning for that.

stackoverflow.com/questions/27392085/cant-link-to-iconv-on-os-x

So, I googled and found the stack overflow question above, and it made me recall what problem it had completely.

So,  this time I would like to record it here.

This is the result with libiconv from Mac Port.

JongAms-Mac-mini:lib jongampark$ nm -m  libiconv.2.dylib | grep iconv

0000000000002db1 (__TEXT,__text) external _libiconv
0000000000002dd3 (__TEXT,__text) external _libiconv_close
000000000000158c (__TEXT,__text) external _libiconv_open

This is the result with libiconv from OS X.

JongAms-Mac-mini:lib jongampark$ nm -m /usr/lib/libiconv.dylib | grep iconv

000000000000301c (__TEXT,__text) external _iconv
000000000000336d (__TEXT,__text) external _iconv_canonicalize
000000000000303e (__TEXT,__text) external _iconv_close
0000000000001c41 (__TEXT,__text) external _iconv_open

So, the difference is that the ones from Mac Port have _lib is prefixed while the ones from OS X don’t.

Also, the included iconv.h file should match with the library file.


Finally I would like to talk about the changes of Xcode behavior.

With a version of 7.x.x, Apple changed that default libraries and header files could be searched without specifying them. Especially, if a library, for example, /usr/lib/libiconv.dylib is linked using the build phase, Xcode didn’t require the /usr/lib is added to the library search path. It was new behavior at that time.

However, they changed it again from some version of Xcode later than the version mentioned above. So, the library path should be set to include /usr/lib.
Without that, even though the /usr/lib/libiconv.dylib is linked by build phase setting (Link Binary with libraries ), Xcode couldn’t find that it’s in /usr/lib.

Apple doesn’t document this kind of changes, and it gives headache.
I wonder why Apple keeps changing from one behavior to the other behavior from time to time. If they keep changing to a newer behavior, it could be understandable, although I don’t like it. However, they are kind of going forward and backward.

This is small difference, but can affect big way.
Apple should document this kind thing and handle this seriously.

Advertisements

A way to get out of the squirrel treadwheel

I was trying to figure out how to create ID2D1Bitmap1 instance which is to be mapped to memory region. But I found out that MSDN documentation put me in self-repeating cycle ( so, I call it squirrel treadwheel. ). In on document it says, the options can’t be used for bitmap instance created with ID2D1DeviceContext, while on the other page, the device context is to be used to create ID2D1Bitmap.

I posted this to MSDN page, ID2D1Bitmap1::Map page.


 

“These flags will be not be able to be used on bitmaps created by the ID2D1DeviceContext”

However on this “ID2D1Bitmap1 interface” page, it says :

Creating ID2D1Bitmap Objects

Use one of these methods to create an ID2D1Bitmap object.

ID2D1DeviceContext::CreateBitmap
ID2D1DeviceContext::CreateBitmapFromWicBitmap

It’s a squirrel’s wheelmill. Don’t you think so?
( this flags can’t be created by ID2D1DeviceContext => on other page, ID2D1Bitmap1 is created using those device context.)

Moreover, throughout Direct2D/DirectWrite and related technology pages, it’s not clear whether methods/functions returns using a parent class pointer ( like ID2D1Bitmap *) can actually return one for its child class instance like ID2D1Bitmap1. By trial and error, I found out that it’s strictly for the stated class. It’s better to be documented. ( Especially you guys are aware of that C++ has supported late binding.)

Secondly, for this issue on how to create ID2D1Bitmap1 with D2D1_MAP_OPTIONS_READ, and thus D2D1_BITMAP_OPTIONS_CANNOT_DRAW | D2D1_BITMAP_OPTIONS_CPU_READ specified in creating an instance of ID2D1Bitmap1, I found some answer here.

The post marked as “Answers”, he created an instance of ID2D1Bitmap1 using CreateBitmap() method of ID2D1DeviceContenxt. It’s opposite to what is mentioned on this page. ( for your convenience, I put it on the top. This document clearly said “These flags will not be able to be used on bitmaps created by ID2D1DeviceContext.” ) You can see that the ID2D1Bitmap1 is created using the device context’s CreateBitmap() method, and it has CPU_READ and CANNOT_DRAW option, and when Map() is called, D2D1_MAP_OPTIONS_READ is specified.

I will test this. But because people marked it as an “Answer”, I sort of believe that it works.

MSDN document is a squirrel treadwheel

D2D1_MAP_OPTIONS enumeration states that D2D1_MAP_OPTIONS_READ is not available on bitmaps created by ID2D1DeviceContext. Then, to figure out how to create ID2D1Bitmap1, which Map() can be used for, if we visit to ID2D1Bitmap1 interface page, it says “use one of these methods to create and ID2D1Bitmap object.

ID2D1DeviceContext::CreateBitmap
ID2D1DeviceContext::CreateBitmapFromWicBitmap

Didn’t it say that D2D1_MAP_OPTIONS_READ is not available for bitamps created by ID2D1DeviceContext?

Shouldn’t there be more way to create ID2D1Bitmap1?
Since 1990, MSDN document has never been good. However, after they adopted “community-based documentation” model, it became even worse. For example, some pages contain just meaningless vague information. Some pages contain sentences which can be understood in many different ways…

Come on, Microsoft people! What are you guys thinking about? Do you guys really think the MSDN document is good?
It’s also creating ID2D1Bitmap1 by “ID2D1DeviceContext”.

OAuth 2 using curl

Trying out OAuth2 via CURL from h[y]tech blog.

It’s good to know that. As a long time user and developer for Unix, I have know cURL. It’s high-level program/library for various protocols and it’s sort of known that it can do everything.
However, buying tech book…? I don’t remember when is my last time such books. Nowadays I rely on Web. (although pedagogy style or explanation styles are not good especially blogs and web site created here in USA. usually Japanese ( of course ) or Korean ( if any ) writing style/books/posts on web are better for more concise and better explanation.

But.. anyway… Today I found very useful blog post on “How to do OAuth 2 with cURL”
Step by step and easy to understand one. It’s good because I don’t need to read MAN pages or documents on Web thoroughly. At least it can be good starting point to get some idea etc. Only when more information is needed, those more official document can be looked up.

More background information is located here : OAuth2: The Resource Owner Password Flow
Official document on OAuth is here : The OAuth 2.0 Authorization Framework

draft-ietf-oauth-v2-31


Of course, these SNS requires OAuth. (1.1 or 2.0+)

 

미국에서 기술 서적을 쓰는 사람들의 전반적인 행태 변화..

80년대, 90년대 중반과 그 후를 비교할 때, 미국에서 기술 문서를 쓰는 사람들은, 진짜 프로그래머에서, 비전공자들, 변호사 혹은 말빨로만 먹고 사는 사람들로 바뀐거 같다. 1판,2판의 C++ Primer (웨이츠 그룹)과 그 후 약 4판인가 5판부터의 것만 비교해봐도 쉽게 알 수 있고, Cocoa Patterns나 Core Data 같은 책을 봐도 알 수 있다. 에디슨 웨슬리의 Core Animation은 저자가 한국 고등학교 수준의 행렬도 못하는 상태에서 쓴 티가 팍팍 난다. 예제를 보다보면 어떻게 어거지로 회전/변환을 맞추기는 하는데, 수학적으로 제대로 되지 않은게 보인다.

Documenting style : Narrative vs. Hybrid style ( Narrative + compact or list based )

There are a couple of style in writing technical documentation. In 80’s and 90’s, it looked to me actual S/W engineers wrote books and document on technical issues. So, at that time, it was full of source code and more compact but easy-to-look-up-later style.

However, somehow from late 90’s, technical document/books became very lengthy and narrative.
So, you should read from the first line to the last line carefully not to miss information. This can be good at first, but let’s say that you already know those information but have to revisit it because you want to make sure some details or you forgot detailed information although you know and remember overall procedure. Then, it slows down things. It’s kind of irritating.

Let’s take one example from Apple’s document.

Providing the Data to the Table View
You must provide data to the table view. This can be done using one of two methods: programmatically by implementing a datasource class or by establishing a relationship between the table view and a controller using Cocoa bindings.

When providing data programmatically you create a class that conforms to the NSTableViewDataSource protocol and implement the method that provides the row and column data as requested. Content can simply be displayed and, when appropriate, can also be edited.

You can also provide content to a table view using Cocoa bindings. Bindings allows you to create a relationship between a controller class instance, which manages the interaction between data objects and the table view. The bindings approach allows you to bypass the datasource class for providing the data as well as supporting editing of the data.

Because the techniques for view-based cell creation and populating and cell-based table view populating and editing are quite different these chapters have been separated by topic.

That’s very narrative. Maybe good for novel, but not technical document. Technical document should allow readers to catch information quickly and thus construct overall idea easily. How about this?

Providing the Data to the Table View
You must provide data to the table view. This can be done using one of two methods:

  • programmatically by implementing a datasource class
  • by establishing a relationship between the table view and a controller using Cocoa bindings.

When providing data programmatically you create a class that conforms to the NSTableViewDataSource protocol and implement the method that provides the row and column data as requested. Content can simply be displayed and, when appropriate, can also be edited.

You can also provide content to a table view using Cocoa bindings. Bindings allows you to create a relationship between a controller class instance, which manages the interaction between data objects and the table view. The bindings approach allows you to bypass the datasource class for providing the data as well as supporting editing of the data.

Because the techniques for view-based cell creation and populating and cell-based table view populating and editing are quite different these chapters have been separated by topic.

Or how about this?

Providing the Data to the Table View
You must provide data to the table view. This can be done using one of two methods:

  • programmatically by implementing a datasource class

You create a class that conforms to the NSTableViewDataSource protocol and implement the method that provides the row and column data as requested. Content can simply be displayed and, when appropriate, can also be edited.

  • by establishing a relationship between the table view and a controller using Cocoa bindings.

You can also provide content to a table view using Cocoa bindings. Bindings allows you to create a relationship between a controller class instance, which manages the interaction between data objects and the table view. The bindings approach allows you to bypass the datasource class for providing the data as well as supporting editing of the data.

Because the techniques for view-based cell creation and populating and cell-based table view populating and editing are quite different these chapters have been separated by topic.

 

The first style with a bullet list is better to grab the fact that there are two ways to achieve it. And when you revisit this issue later, you can quickly catch the idea and refresh your memory more easily. However, when you want to read explanation on those especially for what kind of detailed differences there are, the 1st one still fails. So, the 2nd one is better.

What do you think about it?

%d bloggers like this: